@kweaver-ai/kweaver-sdk 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,139 @@
+# @kweaver-ai/kweaver-sdk
+
+TypeScript SDK and CLI for [KWeaver](https://github.com/kweaver-ai/kweaver-sdk) — gives AI agents and applications programmatic access to knowledge networks and Decision Agents.
+
+[中文文档](README.zh.md)
+
+## Installation
+
+```bash
+# CLI (global)
+npm install -g @kweaver-ai/kweaver-sdk
+
+# Library
+npm install @kweaver-ai/kweaver-sdk
+```
+
+Requires **Node.js >= 22**.
+
+## Quick Start
+
+### Authenticate
+
+```bash
+kweaver auth login https://your-kweaver-instance.com
+```
+
+Or use environment variables:
+
+```bash
+export KWEAVER_BASE_URL=https://your-kweaver-instance.com
+export KWEAVER_TOKEN=your-token
+```
+
+### Simple API (recommended)
+
+```typescript
+import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";
+
+// Zero-config: reads credentials saved by `kweaver auth login`
+kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });
+
+// Search the knowledge network
+const results = await kweaver.search("What risks exist in the supply chain?");
+for (const concept of results.concepts) console.log(concept.concept_name);
+
+// Chat with an agent
+const reply = await kweaver.chat("Summarise the top 3 risks");
+console.log(reply.text);
+
+// After modifying object types or adding datasources, rebuild the BKN index
+await kweaver.weaver({ wait: true });
+
+// List available BKNs and agents
+const bknList   = await kweaver.bkns();
+const agentList = await kweaver.agents();
+```
+
+### Full Client API (advanced)
+
+```typescript
+import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";
+
+// Zero-config: reads credentials saved by `kweaver auth login`
+const client = new KWeaverClient();
+
+// Or pass credentials explicitly
+const client = new KWeaverClient({
+  baseUrl: "https://your-kweaver-instance.com",
+  accessToken: "your-token",
+});
+
+// Knowledge networks
+const kns = await client.knowledgeNetworks.list({ limit: 10 });
+const ots = await client.knowledgeNetworks.listObjectTypes("bkn-id");
+const rts = await client.knowledgeNetworks.listRelationTypes("bkn-id");
+const ats = await client.knowledgeNetworks.listActionTypes("bkn-id");
+
+// Agent chat (single-shot)
+const reply = await client.agents.chat("agent-id", "Hello");
+console.log(reply.text, reply.conversationId);
+
+// Agent chat (streaming)
+await client.agents.stream("agent-id", "Hello", {
+  onTextDelta: (chunk) => process.stdout.write(chunk),
+});
+
+// BKN engine — instance queries, subgraph, action execution
+const instances = await client.bkn.queryInstances("bkn-id", "ot-id", { limit: 20 });
+const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
+await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
+const logs      = await client.bkn.listActionLogs("bkn-id");
+
+// Context Loader (semantic search over a BKN via MCP)
+const cl      = client.contextLoader(mcpUrl, "bkn-id");
+const results = await cl.search({ query: "hypertension treatment" });
+```
+
+## CLI Reference
+
+```
+kweaver auth login/status/list/use/delete/logout
+kweaver token
+kweaver bkn list/get/stats/export/create/update/delete
+kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn relation-type list/get/create/update/delete
+kweaver bkn action-type list/query/execute
+kweaver bkn subgraph
+kweaver bkn action-execution get
+kweaver bkn action-log list/get/cancel
+kweaver agent list/get/chat/sessions/history
+kweaver context-loader config set/use/list/show
+kweaver context-loader kn-search/query-object-instance/...
+kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `KWEAVER_BASE_URL` | KWeaver instance URL |
+| `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
+| `KWEAVER_TOKEN` | Access token |
+
+## Using with AI Agents
+
+Install the KWeaver skill for Claude Code, Cursor, or other AI coding agents:
+
+```bash
+npx skills add kweaver-ai/kweaver-sdk --skill kweaver-core
+```
+
+## Links
+
+- [GitHub](https://github.com/kweaver-ai/kweaver-sdk)
+- [Python SDK on PyPI](https://pypi.org/project/kweaver-sdk/)
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,139 @@
+# @kweaver-ai/kweaver-sdk
+
+KWeaver TypeScript SDK 和 CLI — 让 AI 智能体与应用程序以编程方式访问知识网络和 Decision Agent。
+
+[English](README.md)
+
+## 安装
+
+```bash
+# 全局安装 CLI
+npm install -g @kweaver-ai/kweaver-sdk
+
+# 作为库使用
+npm install @kweaver-ai/kweaver-sdk
+```
+
+需要 **Node.js >= 22**。
+
+## 快速上手
+
+### 认证
+
+```bash
+kweaver auth login https://your-kweaver-instance.com
+```
+
+或使用环境变量：
+
+```bash
+export KWEAVER_BASE_URL=https://your-kweaver-instance.com
+export KWEAVER_TOKEN=your-token
+```
+
+### 简洁 API（推荐）
+
+```typescript
+import kweaver from "@kweaver-ai/kweaver-sdk/kweaver";
+
+// 使用 `kweaver auth login` 保存的凭据，零配置
+kweaver.configure({ config: true, bknId: "your-bkn-id", agentId: "your-agent-id" });
+
+// 搜索知识网络
+const results = await kweaver.search("供应链有哪些关键风险？");
+for (const concept of results.concepts) console.log(concept.concept_name);
+
+// 与 Agent 对话
+const reply = await kweaver.chat("总结前三大风险");
+console.log(reply.text);
+
+// 接入数据源或修改对象类后，重建 BKN 索引
+await kweaver.weaver({ wait: true });
+
+// 查看所有 BKN 和 Agent
+const bknList   = await kweaver.bkns();
+const agentList = await kweaver.agents();
+```
+
+### 底层客户端（高级用法）
+
+```typescript
+import { KWeaverClient } from "@kweaver-ai/kweaver-sdk";
+
+// 零配置：自动读取 `kweaver auth login` 保存的凭据
+const client = new KWeaverClient();
+
+// 或显式传入凭据
+const client = new KWeaverClient({
+  baseUrl: "https://your-kweaver-instance.com",
+  accessToken: "your-token",
+});
+
+// 知识网络
+const kns = await client.knowledgeNetworks.list({ limit: 10 });
+const ots = await client.knowledgeNetworks.listObjectTypes("bkn-id");
+const rts = await client.knowledgeNetworks.listRelationTypes("bkn-id");
+const ats = await client.knowledgeNetworks.listActionTypes("bkn-id");
+
+// Agent 对话（单次）
+const reply = await client.agents.chat("agent-id", "你好");
+console.log(reply.text, reply.conversationId);
+
+// Agent 对话（流式）
+await client.agents.stream("agent-id", "你好", {
+  onTextDelta: (chunk) => process.stdout.write(chunk),
+});
+
+// BKN 引擎：实例查询、子图、Action 执行
+const instances = await client.bkn.queryInstances("bkn-id", "ot-id", { limit: 20 });
+const graph     = await client.bkn.querySubgraph("bkn-id", { /* 路径规格 */ });
+await client.bkn.executeAction("bkn-id", "at-id", { /* 参数 */ });
+const logs      = await client.bkn.listActionLogs("bkn-id");
+
+// Context Loader（通过 MCP 对 BKN 做语义搜索）
+const cl      = client.contextLoader(mcpUrl, "bkn-id");
+const results = await cl.search({ query: "高血压 治疗" });
+```
+
+## 命令速查
+
+```
+kweaver auth login/status/list/use/delete/logout
+kweaver token
+kweaver bkn list/get/stats/export/create/update/delete
+kweaver bkn object-type list/get/create/update/delete/query/properties
+kweaver bkn relation-type list/get/create/update/delete
+kweaver bkn action-type list/query/execute
+kweaver bkn subgraph
+kweaver bkn action-execution get
+kweaver bkn action-log list/get/cancel
+kweaver agent list/get/chat/sessions/history
+kweaver context-loader config set/use/list/show
+kweaver context-loader kn-search/query-object-instance/...
+kweaver call <path> [-X METHOD] [-d BODY] [-H header]
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `KWEAVER_BASE_URL` | KWeaver 实例地址 |
+| `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
+| `KWEAVER_TOKEN` | 访问令牌 |
+
+## 在 AI 智能体中使用
+
+为 Claude Code、Cursor 等 AI 编程助手安装 KWeaver 技能：
+
+```bash
+npx skills add kweaver-ai/kweaver-sdk --skill kweaver-core
+```
+
+## 相关链接
+
+- [GitHub](https://github.com/kweaver-ai/kweaver-sdk)
+- [Python SDK on PyPI](https://pypi.org/project/kweaver-sdk/)
+
+## 许可证
+
+MIT

package/dist/api/agent-list.d.ts

@@ -10,3 +10,54 @@ export interface ListAgentsOptions {
     is_to_square?: number;
 }
 export declare function listAgents(options: ListAgentsOptions): Promise<string>;
+export interface GetAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    businessDomain?: string;
+}
+export declare function getAgent(options: GetAgentOptions): Promise<string>;
+export interface GetAgentByKeyOptions {
+    baseUrl: string;
+    accessToken: string;
+    key: string;
+    businessDomain?: string;
+}
+export declare function getAgentByKey(options: GetAgentByKeyOptions): Promise<string>;
+export interface CreateAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    body: string;
+    businessDomain?: string;
+}
+export declare function createAgent(options: CreateAgentOptions): Promise<string>;
+export interface UpdateAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    body: string;
+    businessDomain?: string;
+}
+export declare function updateAgent(options: UpdateAgentOptions): Promise<string>;
+export interface DeleteAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    businessDomain?: string;
+}
+export declare function deleteAgent(options: DeleteAgentOptions): Promise<void>;
+export interface PublishAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    body?: string;
+    businessDomain?: string;
+}
+export declare function publishAgent(options: PublishAgentOptions): Promise<string>;
+export interface UnpublishAgentOptions {
+    baseUrl: string;
+    accessToken: string;
+    agentId: string;
+    businessDomain?: string;
+}
+export declare function unpublishAgent(options: UnpublishAgentOptions): Promise<void>;

package/dist/api/agent-list.js

@@ -1,4 +1,14 @@
 import { HttpError } from "../utils/http.js";
+function buildHeaders(accessToken, businessDomain) {
+    return {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-CN",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-CN",
+    };
+}
 export async function listAgents(options) {
     const { baseUrl, accessToken, businessDomain = "bd_public", name = "", offset = 0, limit = 50, category_id = "", custom_space_id = "", is_to_square = 1, } = options;
     const base = baseUrl.replace(/\/+$/, "");
@@ -11,16 +21,53 @@ export async function listAgents(options) {
         custom_space_id,
         is_to_square,
     });
+    const response = await fetch(url, {
+        method: "POST",
+        headers: buildHeaders(accessToken, businessDomain),
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function getAgent(options) {
+    const { baseUrl, accessToken, agentId, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function getAgentByKey(options) {
+    const { baseUrl, accessToken, key, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/by-key/${encodeURIComponent(key)}`;
+    const response = await fetch(url, {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function createAgent(options) {
+    const { baseUrl, accessToken, body, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent`;
     const response = await fetch(url, {
         method: "POST",
         headers: {
-            accept: "application/json, text/plain, */*",
-            "accept-language": "zh-CN",
-            authorization: `Bearer ${accessToken}`,
-            token: accessToken,
-            "x-business-domain": businessDomain,
-            "x-language": "zh-CN",
-            "x-requested-with": "XMLHttpRequest",
+            ...buildHeaders(accessToken, businessDomain),
             "content-type": "application/json",
         },
         body,
@@ -31,3 +78,65 @@ export async function listAgents(options) {
     }
     return responseBody;
 }
+export async function updateAgent(options) {
+    const { baseUrl, accessToken, agentId, body, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}`;
+    const response = await fetch(url, {
+        method: "PUT",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function deleteAgent(options) {
+    const { baseUrl, accessToken, agentId, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}`;
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    if (!response.ok) {
+        const responseBody = await response.text();
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+}
+export async function publishAgent(options) {
+    const { baseUrl, accessToken, agentId, body = "{}", businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}/publish`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    return responseBody;
+}
+export async function unpublishAgent(options) {
+    const { baseUrl, accessToken, agentId, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-factory/v3/agent/${encodeURIComponent(agentId)}/unpublish`;
+    const response = await fetch(url, {
+        method: "PUT",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    if (!response.ok) {
+        const responseBody = await response.text();
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+}

package/dist/api/bkn-backend.d.ts

@@ -0,0 +1,16 @@
+export interface UploadBknOptions {
+    baseUrl: string;
+    accessToken: string;
+    tarBuffer: Buffer;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function uploadBkn(options: UploadBknOptions): Promise<string>;
+export interface DownloadBknOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    businessDomain?: string;
+    branch?: string;
+}
+export declare function downloadBkn(options: DownloadBknOptions): Promise<Buffer>;

package/dist/api/bkn-backend.js

@@ -0,0 +1,46 @@
+import { HttpError } from "../utils/http.js";
+function buildHeaders(accessToken, businessDomain) {
+    return {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-cn",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-cn",
+    };
+}
+export async function uploadBkn(options) {
+    const { baseUrl, accessToken, tarBuffer, businessDomain = "bd_public", branch = "main", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/bkn-backend/v1/bkns`);
+    url.searchParams.set("branch", branch);
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(tarBuffer)], { type: "application/octet-stream" }), "bkn.tar");
+    const headers = buildHeaders(accessToken, businessDomain);
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers,
+        body: form,
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}
+export async function downloadBkn(options) {
+    const { baseUrl, accessToken, knId, businessDomain = "bd_public", branch = "main", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/bkn-backend/v1/bkns/${encodeURIComponent(knId)}`);
+    url.searchParams.set("branch", branch);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}

package/dist/api/datasources.d.ts

@@ -0,0 +1,73 @@
+export interface TestDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    password: string;
+    schema?: string;
+    businessDomain?: string;
+}
+export declare function testDatasource(options: TestDatasourceOptions): Promise<void>;
+export interface CreateDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    name: string;
+    type: string;
+    host: string;
+    port: number;
+    database: string;
+    account: string;
+    password: string;
+    schema?: string;
+    comment?: string;
+    businessDomain?: string;
+}
+export declare function createDatasource(options: CreateDatasourceOptions): Promise<string>;
+export interface ListDatasourcesOptions {
+    baseUrl: string;
+    accessToken: string;
+    keyword?: string;
+    type?: string;
+    businessDomain?: string;
+}
+export declare function listDatasources(options: ListDatasourcesOptions): Promise<string>;
+export interface GetDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function getDatasource(options: GetDatasourceOptions): Promise<string>;
+export interface DeleteDatasourceOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function deleteDatasource(options: DeleteDatasourceOptions): Promise<void>;
+export interface ListTablesOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+    businessDomain?: string;
+}
+export declare function listTables(options: ListTablesOptions): Promise<string>;
+export interface ListTablesWithColumnsOptions extends ListTablesOptions {
+    autoScan?: boolean;
+}
+/** List tables with column details. Optionally triggers metadata scan if no tables found. */
+export declare function listTablesWithColumns(options: ListTablesWithColumnsOptions): Promise<string>;
+export interface ScanMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    dsType?: string;
+    businessDomain?: string;
+}
+export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;