@kweaver-ai/kweaver-sdk

v0.8.3

Published

4 days ago

KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.

0High
0Medium
0Low

cli typescript kweaver

@kweaver-ai/kweaver-sdk

KWeaver TypeScript SDK 和 CLI — 让 AI 智能体与应用程序以编程方式访问知识网络和 Decision Agent。

English

安装

# 全局安装 CLI
npm install -g @kweaver-ai/kweaver-sdk

# 作为库使用
npm install @kweaver-ai/kweaver-sdk

需要 Node.js >= 22。

API 参考（TypeDoc）

由源码与 TSDoc 生成 HTML，产物在 docs/reference/typescript-api-html/index.html（已 gitignore）。typedoc.json 用 entryPointStrategy: "expand" 自动展开 src/resources、src/api、src/auth 整目录，新增模块无需改配置。英文构建用 README.md，中文构建用 README.zh.md。「Defined in」 链接的 gitRevision 取 TYPEDOC_GIT_REVISION → GITHUB_SHA → 回退 "main"；CI 中固定到当前 SHA：TYPEDOC_GIT_REVISION=$GITHUB_SHA npm run docs。

TypeDoc 不会在同一个站点里提供中英文切换。做法是生成两套目录：英文界面（默认）与中文界面（npm run docs:zh），主要翻译导航等界面文案；API 说明仍以源码里的 TSDoc（英文）为准。

cd packages/typescript
npm install
npm run docs             # 英文界面 → docs/reference/typescript-api-html/
npm run docs:serve       # 生成并访问 http://127.0.0.1:8766
npm run docs:zh          # 中文界面 + README.zh.md → docs/reference/typescript-api-html-zh/
npm run docs:serve:zh    # 生成并访问 http://127.0.0.1:8767
npm run docs:all         # 两套产物都生成

docs/reference/** 下的所有文件均为生成产物。请编辑 packages/typescript/README*.md 与源码 TSDoc 注释；media/ 下的拷贝在下次构建时会被覆盖。

快速上手

认证

kweaver auth login https://your-kweaver-instance.com

或使用环境变量：

export KWEAVER_BASE_URL=https://your-kweaver-instance.com
export KWEAVER_TOKEN=your-token

两者同时设置时，即使未执行 auth login，业务命令也会使用该 token。若 ~/.kweaver/ 无当前平台，仍可使用 kweaver auth status、kweaver auth whoami（支持 --json）、kweaver config show。环境变量模式下，whoami 会通过 EACP /api/eacp/v1/user/get 在线获取身份并展示 Type（user/app）、User ID、Account、Name，对 opaque 与 JWT token 都生效；若 EACP 不可达，则回退到本地 JWT 解码，opaque token 会给出简短提示。

kweaver config list-bd 用于列出当前用户可访问的业务域。应用（service）token 没有绑定终端用户——当后端返回 401 invalid user_id 时，CLI 会再向 EACP 复核 token 类型，确认为 type:"app" 后将晦涩的后端原文替换为 This command does not support app accounts.。需要这个能力时请改用交互式 auth login 获得的用户 token。

业务域（平台配置）

在调用依赖租户范围的接口前，应先确认业务域；DIP 环境通常使用 UUID，不能长期只依赖默认 bd_public。

kweaver config show
kweaver config list-bd
kweaver config set-bd <uuid>

kweaver auth login 成功后，若尚未配置，CLI 可能自动选择业务域。也可用环境变量 KWEAVER_BUSINESS_DOMAIN 或各命令的 -bd / --biz-domain 覆盖。详见 ../../skills/kweaver-core/references/config.md。

简洁 API（推荐）

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();

底层客户端（高级用法）

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");

// 数据源 & vega-backend 资源
const dsList    = await client.datasources.list();
const resId     = await client.resources.create({ name: "v", datasourceId: "ds-id", table: "orders" });
const resList   = await client.resources.list({ datasourceId: "ds-id" });
const fuzzy     = await client.resources.find("BOM", { wait: false });
const exact     = await client.resources.find("orders", {
  datasourceId: "ds-id",
  exact: true,
  wait: true,
});
const res       = await client.resources.get(resId);
const queryRows = await client.resources.query(resId, { limit: 10, needTotal: true });

// Vega — 可观测性与查询
const catalogs = await client.vega.listCatalogs();
const health   = await client.vega.health();
// 结构化查询 — POST /api/vega-backend/v1/query/execute（body 为 JSON 字符串）
const structured = await client.vega.executeQuery(
  JSON.stringify({ tables: [{ resource_id: "res-1" }], output_fields: ["*"], limit: 20 }),
);
// 直连 SQL 或 OpenSearch DSL — POST /api/vega-backend/v1/resources/query
// 使用 {{resource_id}} 占位符以路由到正确的 catalog connector
const rows = await client.vega.sqlQuery(
  JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
);

// Context Loader（MCP search_schema + 通用 tools/call）
const cl      = client.contextLoader(mcpUrl, "bkn-id");
const schema  = await cl.searchSchema({
  query: "高血压 治疗",
  search_scope: { concept_groups: ["clinical"] },
});
const rawTool = await cl.callTool("search_schema", { query: "高血压 治疗" });

// Skill（注册表/市场/渐进式读取）
const skills = await client.skills.market({ name: "kweaver" });
const skillMd = await client.skills.fetchContent("skill-id");
const draft = await client.skills.updateMetadata("skill-id", {
  name: "Demo",
  description: "Demo skill",
  category: "system",
});
const history = await client.skills.history("skill-id");

searchSchema() 是 Context Loader MCP search_schema 的类型化封装，默认 response_format 为 json，支持 query、response_format、search_scope、max_concepts、schema_brief、enable_rerank。search_scope.concept_groups 用于按 BKN 概念分组 ID 限定 Schema 发现范围，不是实例数据过滤条件。解析后的返回结果可能包含 object_types、relation_types、action_types、metric_types。

client.bkn.knSearch(...) 已过时。新接入的 Schema 发现请使用 client.contextLoader(...).searchSchema(...)。

需要直接使用 MCP 原生 tools/call 时，使用 callTool(name, args)。这适用于服务端新增工具但 SDK 尚未提供类型化封装的场景，参数会原样透传。

命令速查

kweaver 采用 gh 风格 help 布局（详见 docs/cli_conventions.md §8）：

kweaver --help                            # gh 风格顶层概览
kweaver help <command>                    # 转发到 `<command> --help`
kweaver help all                          # 完整 per-action 签名（迁移期兜底）
kweaver <command> --help                  # 子命令概览 + 动作列表
kweaver <command> <subcommand> --help     # 动作级 flag + 示例

顶层命令分组：

AUTHENTICATION & CONFIG  auth · token · config
DECISION AGENT           agent · toolbox · tool
AI DATA PLATFORM         bkn · ds · resource · dataflow · vega · context-loader
TRACE AI                 trace
FOUNDATION               call · explore · model · skill · help

需要查阅每个动作的完整签名（可浏览 / 可 grep）时，运行 kweaver help all。

Dataflow CLI 示例

kweaver dataflow list
kweaver dataflow run <dagId> --file ./demo.pdf
kweaver dataflow run <dagId> --url https://example.com/demo.pdf --name demo.pdf
kweaver dataflow runs <dagId>
kweaver dataflow runs <dagId> --since 2026-04-01
kweaver dataflow logs <dagId> <instanceId>
kweaver dataflow logs <dagId> <instanceId> --detail

kweaver dataflow runs --since 会按本地自然日过滤；如果参数无法被 new Date(...) 解析，CLI 会回退到最近 20 条运行记录。kweaver dataflow logs 默认输出摘要；加上 --detail 会打印带缩进的 input 和 output 载荷。

模型工厂 CLI 示例

mf-model-manager：/api/mf-model-manager/v1（配置 CRUD、test）
mf-model-api：/api/mf-model-api/v1（OpenAI 兼容 chat，以及小模型 embeddings / rerank）

离线模版：model llm --template / model small --template 输出内置 basic JSON（不调后端）。大模型 model_type 在后端仅为 llm（文本）、rlm（推理）、vu（视觉/多模态，接口缩写不是 vlm）；列表过滤：kweaver model llm list --type …。详见 skills/kweaver-core/references/model.md。

kweaver model llm list --limit 30
kweaver model llm list --type vu
kweaver model llm chat <model_id> -m "你好" --no-stream
kweaver model llm --template > ./llm.json
kweaver model small add --name my-emb --type embedding --batch-size 8 --max-tokens 512 --embedding-dim 1536 \
  --model-config-file ./cfg.json
kweaver model small embeddings <model_id> -i "hello" -i "world"
kweaver model small rerank <model_id> -q "查询" -d "文档a" -d "文档b"
kweaver model small --template > ./embedding-model-config.json

完整说明见 skills/kweaver-core/references/model.md 与 kweaver model --help。

Vega `sql` CLI 示例

对 Catalog 资源执行直连 SQL（POST /api/vega-backend/v1/resources/query）。SQL 中使用 {{<resource_id>}} 或 {{.<resource_id>}}（资源 id 来自 vega resource list / get），后端据此解析物理表与 connector。--resource-type 为目标数据源的连接器类型，可通过 kweaver vega connector-type list 查看。简单模式下请用引号包住整个 --query 参数，避免 shell 对花括号做特殊处理。

# 简单模式（推荐）：避免在 JSON 里转义整段 SQL
kweaver vega sql --resource-type mysql --query "SELECT * FROM {{res-1}} LIMIT 5"

# 高级模式：完整 JSON（可带 query_timeout、stream_size，或 OpenSearch DSL 对象等）
kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} LIMIT 5"}'

若同时提供 -d 与 --query / --resource-type，仅以 -d 为准。

无 OAuth 的平台： 使用 kweaver auth <url> --no-auth，或照常 auth login；若 POST /oauth2/clients 返回 404，CLI 会提示并自动保存为 no-auth。凭据仍在 ~/.kweaver/，可用 auth use / auth list 切换。可选环境变量 KWEAVER_NO_AUTH=1（未设置 KWEAVER_TOKEN 时）配合 KWEAVER_BASE_URL。SDK：new KWeaverClient({ baseUrl, auth: false }) 或 kweaver.configure({ baseUrl, auth: false })。

环境变量

| 变量 | 说明 | |---|---| | KWEAVER_BASE_URL | KWeaver 实例地址 | | KWEAVER_MF_MODEL_MANAGER_URL | 可选：mf-model-manager API 根地址（默认 KWEAVER_BASE_URL + /api/mf-model-manager/v1） | | KWEAVER_MF_MODEL_API_URL | 可选：mf-model-api 根地址（默认 KWEAVER_BASE_URL + /api/mf-model-api/v1） | | KWEAVER_BUSINESS_DOMAIN | 业务域标识 | | KWEAVER_TOKEN | 访问令牌 | | KWEAVER_TOKEN_SOURCE | CLI 传入 --token 时由程序设置的内部标记；请勿手动设置 | | KWEAVER_NO_AUTH | 设为 1/true/yes 且未设置 KWEAVER_TOKEN 时使用 no-auth 占位（需 KWEAVER_BASE_URL 或已选平台） | | KWEAVER_TLS_INSECURE | 设为 1 或 true 时跳过 TLS 证书校验（仅开发；更推荐 kweaver auth … --insecure 以按平台持久化） | | NODE_TLS_REJECT_UNAUTHORIZED | Node.js 内置 TLS 开关：设为 0 时在本进程内跳过 HTTPS 证书校验。kweaver 在 KWEAVER_TLS_INSECURE 生效或已保存 token 为不安全 TLS 时会设置此项（范围同上；仅开发）。 |

Stateless token 模式

通过 --token 传入访问令牌，该次调用对该 token 路径既不读也不写 ~/.kweaver/：

kweaver --base-url https://platform.example.com --token "$TOK" bkn list

来源优先级：

| 来源 | base-url | token | |------|----------|-------| | flag | --base-url | --token | | env | KWEAVER_BASE_URL | KWEAVER_TOKEN | | 磁盘 | active platform | OAuth 会话（可 refresh） |

--token 模式下会禁用写盘命令：auth login / logout / use / delete / switch、config set-bd、整个 context-loader config 子命令组 ——去掉 --token 或改用 kweaver auth login。

auth whoami / auth status 通过文案区分来源：flag 模式为 CLI (flag: --token)，env 模式为 env (KWEAVER_TOKEN)（whoami --json 为 "source": "flag" 与 "source": "env"）。

kweaver context-loader 运行时子命令将 <kn-id> 作为第一个位置参数（如 kweaver context-loader tools <kn-id>），也支持全局 --kn-id <id> / -k <id> flag，因此在 stateless 模式下可直接使用，无需任何持久化配置。调试参数时可先执行 kweaver context-loader help <subcommand> 或 <subcommand> --help，这些 help 路径不会触发登录、配置读取或网络请求。context-loader config set|use|list|remove|show 管理子命令已被标记为 deprecated（每次调用打印警告），且在 --token 下整组被禁用。

TLS 证书问题排查

如果遇到 fetch failed、self-signed certificate、UNABLE_TO_GET_ISSUER_CERT 等 TLS 相关错误，通常是目标服务器使用了自签名证书或 Kubernetes Ingress 默认假证书。可按优先级尝试以下方案：

推荐（按平台持久化） — 登录时加 --insecure：
```
kweaver auth login https://your-host --insecure
# 或简写
kweaver auth login https://your-host -k
```
该标记会写入 ~/.kweaver/ 的 token.json，后续所有 CLI 命令对该平台自动生效，无需额外操作。
临时生效（当前 shell） — 设置环境变量：
```
export KWEAVER_TLS_INSECURE=1
kweaver bkn list
```
Node.js 原生方式 — 直接设置 NODE_TLS_REJECT_UNAUTHORIZED：
```
NODE_TLS_REJECT_UNAUTHORIZED=0 kweaver bkn list
```

安全提示： 以上方式均会跳过 HTTPS 证书校验，仅适用于开发/内网环境。生产环境请使用受信任的 CA 签发证书。

无浏览器 / 服务器端认证

适用于 SSH 远程服务器、CI 环境等无浏览器场景：

第一步 — 有浏览器的机器： 正常运行 kweaver auth login。登录成功后，回调页面会显示一条可复制的命令（含 --client-id、--client-secret、--refresh-token）。也可以用 kweaver auth export 查看。

第二步 — 在没有浏览器的那台机器上： 在 SSH 服务器、CI 等环境中执行下面这条命令：

kweaver auth login https://your-platform \
  --client-id abc123 \
  --client-secret def456 \
  --refresh-token ghi789

SDK 会用 refresh token 换取新的 access token 并保存到本地，之后自动续期正常工作。

在 AI 智能体中使用

为 Claude Code、Cursor 等 AI 编程助手安装 KWeaver 技能：

npx skills add kweaver-ai/kweaver-sdk --skill kweaver-core

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@kweaver-ai/kweaver-sdk

安装

API 参考（TypeDoc）

快速上手

认证

业务域（平台配置）

简洁 API（推荐）

底层客户端（高级用法）

命令速查

Dataflow CLI 示例

模型工厂 CLI 示例

Vega sql CLI 示例

环境变量

Stateless token 模式

TLS 证书问题排查

无浏览器 / 服务器端认证

在 AI 智能体中使用

相关链接

许可证

Vega `sql` CLI 示例