kweaver-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KWeaver CLI

KWeaver 平台的命令行工具，覆盖认证、平台业务域（

config

）、知识网络管理与查询、Agent CRUD 与对话、数据源管理。

Command-line tool for the KWeaver platform, covering authentication, platform business domain (

config

), knowledge network management and query, Agent CRUD and conversation, data source management.

安装

Installation

bash

npm install -g @kweaver-ai/kweaver-sdk

需 Node.js 22+。也可用

npx kweaver

临时运行。

bash

npm install -g @kweaver-ai/kweaver-sdk

Requires Node.js 22+. You can also run it temporarily with

npx kweaver

使用方式

Usage

bash

kweaver [--user <userId|username>] <command> [subcommand] [options]

完整子命令与参数以当前安装的 CLI 为准：运行

kweaver --help

（或

-h

）查看与代码同步的用法列表；查版本用

kweaver --version

-V

kweaver version

。子命令细节用

kweaver <group> <subcommand> --help

（例如

kweaver auth --help

、

kweaver bkn push --help

）。

本 skill 下的

references/*.md

与 CLI 行为对齐；表格与 reference 为速查，新增标志（如

auth

的

--alias

、BKN

validate

push

的编码选项）在 reference 中有说明。

别名：

kweaver curl

等同于

kweaver call

；

kweaver context

等同于

kweaver context-loader

。

业务域（business domain）：多数请求依赖

x-business-domain

。

kweaver auth login

后应优先执行

kweaver config show

；列表为空时用

config list-bd

查看平台可选域，再

config set-bd <uuid>

。详见

references/config.md

。

bash

kweaver [--user <userId|username>] <command> [subcommand] [options]

Complete subcommands and parameters are subject to the currently installed CLI: Run

kweaver --help

(or

-h

) to view the usage list synchronized with the code; check the version with

kweaver --version

-V

kweaver version

. For details of subcommands, use

kweaver <group> <subcommand> --help

(e.g.,

kweaver auth --help

kweaver bkn push --help

The

references/*.md

files under this skill align with CLI behaviors; tables and references are quick references, and new flags (such as

--alias

for

auth

, encoding options for BKN

validate

push

) are explained in the references.

Aliases:

kweaver curl

is equivalent to

kweaver call

;

kweaver context

is equivalent to

kweaver context-loader

Business domain: Most requests depend on

x-business-domain

. After

kweaver auth login

, you should first execute

kweaver config show

; if the list is empty, use

config list-bd

to view optional domains on the platform, then

config set-bd <uuid>

. See

references/config.md

for details.

使用前提

Prerequisites

认证凭据通过
~/.kweaver/
管理。默认操作：在存在
refresh_token
时，用 OAuth2
refresh_token
授权换发新的
access_token
（过期或临近过期时自动执行，无需额外参数）。禁止提前检查环境变量，禁止询问用户提供密码或 Token。

Authentication credentials are managed via
~/.kweaver/
. Default behavior: When a
refresh_token
exists, use OAuth2
refresh_token
authorization to obtain a new
access_token
(automatically executed when expired or nearly expired, no additional parameters required). Prohibited to check environment variables in advance, prohibited to ask users for passwords or Tokens.

认证优先级

Authentication Priority

```
KWEAVER_TOKEN
```
+
```
KWEAVER_BASE_URL
```
环境变量 → 静态 Token（如存在则优先使用，不会用 refresh 换发）
```
~/.kweaver/
```
凭据（
```
kweaver auth login
```
写入）→ 默认用 refresh_token 换发 access_token（推荐）
```
KWEAVER_USER
```
环境变量（或全局
```
--user
```
参数）→ 使用指定用户的凭证，不切换活跃用户

```
KWEAVER_TOKEN
```
+
```
KWEAVER_BASE_URL
```
environment variables → Static Token (used preferentially if present, will not use refresh to obtain a new token)
Credentials in
```
~/.kweaver/
```
(written by
```
kweaver auth login
```
) → Default use refresh_token to obtain access_token (recommended)
```
KWEAVER_USER
```
environment variable (or global
```
--user
```
parameter) → Use credentials of the specified user, do not switch active users

业务域优先级（与认证独立）

Business Domain Priority (Independent of Authentication)

```
KWEAVER_BUSINESS_DOMAIN
```
环境变量

当前平台

config.json

中的

businessDomain

（

kweaver config set-bd

）

默认
```
bd_public
```
（首次登录后 CLI 可能已自动写入更合适的值）

```
KWEAVER_BUSINESS_DOMAIN
```
environment variable

businessDomain

in the current platform's

config.json

(set via

kweaver config set-bd

)

Default
```
bd_public
```
(the CLI may have automatically written a more appropriate value after the first login)

命令组总览

Command Group Overview

命令组	说明	常用命令	详细参考
`auth`	认证管理（支持多账号）	`auth login <url> [--alias name]` （简写： `auth <url> [--alias …]` ）；可选 `--no-browser` 、 `-u/-p` HTTP `/oauth2/signin` ；初始密码（401001017）下 TTY 可交互改密，脚本用 `--new-password` ； `auth change-password [<url>] [-u …]` （EACP 改密；URL 与 `-u` 都可省略，分别回退到当前平台与当前激活账号；无需 token）； `auth list` / `auth users` / `auth switch` ；全局 `--user` / `KWEAVER_USER` ；无当前平台时 `auth status` / `whoami` 可用 env 兜底（见 `references/auth.md` ）	`references/auth.md`
`token`	打印当前 access token（自动刷新）	`token`	—
`config`	平台业务域（优先于多数 bkn/agent/ds 操作）	`config show` , `config list-bd` , `config set-bd <uuid>`	`references/config.md`
`bkn`	BKN 知识网络管理、Schema、查询、Action	`bkn validate` / `push` 默认检测 `.bkn` 编码并规范为 UTF-8，可用 `--no-detect-encoding` 或 `--source-encoding gb18030` ；另有 `pull` 、 `object-type` 、 `search` 、 `create-from-ds` / `create-from-csv` 等，见 `references/bkn.md`	`references/bkn.md`
`agent`	Agent CRUD、发布、对话、Trace、模板、分类	`agent list` , `agent get <id>` , `agent create --name <n> --profile <p> --config <json>` , `agent publish <id> --category-id <cid>` , `agent chat <id> -m "..."` 、 `agent category-list` , `agent template-list` , `agent template-get <tpl_id>` 、 `agent sessions <agent_id>` 、 `agent history <conversation_id>` 、 `agent trace <conversation_id>`	`references/agent.md`
`ds`	数据源管理	`ds list` , `ds get <id>` , `ds import-csv <ds_id> --files <glob> [--recreate]`	`references/ds.md`
`dataview`	数据视图（mdl-data-model / vega-backend）	`dataview list` 、 `find --name` 、 `get` 、 `query` 、 `delete` ；BKN 绑定也可用 `vega resource` ID（type=resource）	`references/dataview.md`
`dataflow`	Dataflow 文档流程	`dataflow list` , `dataflow run <dagId> --file <path>` , `dataflow run <dagId> --url <remote-url> --name <filename>` , `dataflow runs <dagId> [--since <date-like>]` , `dataflow logs <dagId> <instanceId> [--detail]`	`references/dataflow.md`
`skill`	Skill 注册、市场查找、渐进式读取、下载与安装	`skill list` 、 `market` 、 `register --zip-file` 、 `content` 、 `read-file` 、 `install`	`references/skill.md`
`toolbox`	平台工具箱（toolbox）管理	`toolbox create --name <n> --service-url <url>` 、 `toolbox list` 、 `toolbox publish/unpublish <id>` 、 `toolbox delete <id> [-y]`	`references/toolbox.md`
`tool`	工具箱内 tool 注册与启停（OpenAPI）	`tool upload --toolbox <id> <openapi-spec>` 、 `tool list --toolbox <id>` 、 `tool enable/disable --toolbox <id> <tool-id>...`	`references/tool.md`
`vega`	Vega 可观测平台	`vega health` , `vega catalog list` , `vega resource list` , `vega query execute -d <json>` , `vega sql --resource-type <t> --query "<sql>"` / `vega sql -d <json>`	`references/vega.md`
`context-loader`	MCP 分层检索	`context-loader config show` , `context-loader kn-search <query>`	`references/context-loader.md`
`call`	通用 API 调用	`call <url> [-X POST] [-d '...']` （可用 `curl` 别名；支持 `--url` 、 `--data-raw` 等，见 `kweaver --help` ）	`references/call.md`

Command Group	Description	Common Commands	Detailed Reference
`auth`	Authentication management (supports multiple accounts)	`auth login <url> [--alias name]` (shortened: `auth <url> [--alias …]` ); optional `--no-browser` , `-u/-p` for HTTP `/oauth2/signin` ; initial password (401001017) allows interactive password change in TTY, use `--new-password` in scripts; `auth change-password [<url>] [-u …]` (EACP password change; both URL and `-u` can be omitted, falling back to the current platform and current active account respectively; no token required); `auth list` / `auth users` / `auth switch` ; global `--user` / `KWEAVER_USER` ; when there is no current platform, `auth status` / `whoami` can use env as fallback (see `references/auth.md` )	`references/auth.md`
`token`	Print current access token (auto-refreshed)	`token`	—
`config`	Platform business domain (prioritized over most bkn/agent/ds operations)	`config show` , `config list-bd` , `config set-bd <uuid>`	`references/config.md`
`bkn`	BKN knowledge network management, Schema, query, Action	`bkn validate` / `push` detects `.bkn` encoding by default and normalizes it to UTF-8; use `--no-detect-encoding` or `--source-encoding gb18030` if needed; other commands include `pull` , `object-type` , `search` , `create-from-ds` / `create-from-csv` , etc., see `references/bkn.md`	`references/bkn.md`
`agent`	Agent CRUD, publish, conversation, Trace, templates, categories	`agent list` , `agent get <id>` , `agent create --name <n> --profile <p> --config <json>` , `agent publish <id> --category-id <cid>` , `agent chat <id> -m "..."` , `agent category-list` , `agent template-list` , `agent template-get <tpl_id>` , `agent sessions <agent_id>` , `agent history <conversation_id>` , `agent trace <conversation_id>`	`references/agent.md`
`ds`	Data source management	`ds list` , `ds get <id>` , `ds import-csv <ds_id> --files <glob> [--recreate]`	`references/ds.md`
`dataview`	Data view (mdl-data-model / vega-backend)	`dataview list` , `find --name` , `get` , `query` , `delete` ; BKN binding can also use `vega resource` ID (type=resource)	`references/dataview.md`
`dataflow`	Dataflow document processes	`dataflow list` , `dataflow run <dagId> --file <path>` , `dataflow run <dagId> --url <remote-url> --name <filename>` , `dataflow runs <dagId> [--since <date-like>]` , `dataflow logs <dagId> <instanceId> [--detail]`	`references/dataflow.md`
`skill`	Skill registration, market search, progressive reading, download and installation	`skill list` , `market` , `register --zip-file` , `content` , `read-file` , `install`	`references/skill.md`
`toolbox`	Platform toolbox management	`toolbox create --name <n> --service-url <url>` , `toolbox list` , `toolbox publish/unpublish <id>` , `toolbox delete <id> [-y]`	`references/toolbox.md`
`tool`	Tool registration, start and stop in toolbox (OpenAPI)	`tool upload --toolbox <id> <openapi-spec>` , `tool list --toolbox <id>` , `tool enable/disable --toolbox <id> <tool-id>...`	`references/tool.md`
`vega`	Vega observability platform	`vega health` , `vega catalog list` , `vega resource list` , `vega query execute -d <json>` , `vega sql --resource-type <t> --query "<sql>"` / `vega sql -d <json>`	`references/vega.md`
`context-loader`	MCP hierarchical retrieval	`context-loader config show` , `context-loader kn-search <query>`	`references/context-loader.md`
`call`	General API call	`call <url> [-X POST] [-d '...']` (can use `curl` alias; supports `--url` , `--data-raw` , etc., see `kweaver --help` )	`references/call.md`

操作指南

Operation Guide

场景	说明	详细参考
登录后确认业务域	`config show` ；若异常或列表为空 → `config list-bd` → `config set-bd <uuid>`	references/config.md
从数据库/CSV 构建 KN	连接数据源 → CSV 导入 → 创建 KN → 构建索引 → 查询验证 → 绑定 Agent	references/build-kn-from-db.md
CLI 排障速查	权限、pull、build、import、dataview SQL 等	references/troubleshooting.md
列/查数据视图	`list` 浏览； `find --name` 按名搜索（ `--exact` / `--wait` ）； `query` 对视图跑 SQL	references/dataview.md
管理 Dataflow 文档流程	`list` 看 DAG； `run` 触发本地文件或远程 URL； `runs --since` 看自然日运行记录； `logs --detail` 查步骤载荷	references/dataflow.md
Trace 数据分析	`agent trace <conversation_id>` 获取 trace 数据，构建证据链	—
管理 Skill	`list` / `market` 查找 Skill； `content` / `read-file` 渐进式读取； `install` 下载并解压本地使用	references/skill.md
注册外部工具	`toolbox create` 建箱 → `tool upload` 上传 OpenAPI → `tool list` 拿 `tool_id` → `tool enable` 启用 → `toolbox publish` 切到 published	references/toolbox.md · references/tool.md

按需阅读：需要子命令完整参数或编排示例时，读取对应的 reference 文件。

Scenario	Description	Detailed Reference
Confirm business domain after login	`config show` ; if abnormal or empty → `config list-bd` → `config set-bd <uuid>`	references/config.md
Build KN from database/CSV	Connect data source → Import CSV → Create KN → Build index → Query verification → Bind Agent	references/build-kn-from-db.md
CLI troubleshooting quick reference	Permissions, pull, build, import, dataview SQL, etc.	references/troubleshooting.md
List/query data views	`list` to browse; `find --name` to search by name ( `--exact` / `--wait` ); `query` to run SQL on views	references/dataview.md
Manage Dataflow document processes	`list` to view DAGs; `run` to trigger local files or remote URLs; `runs --since` to view daily run records; `logs --detail` to check step payloads	references/dataflow.md
Trace data analysis	`agent trace <conversation_id>` to obtain trace data and build evidence chain	—
Manage Skill	`list` / `market` to find Skills; `content` / `read-file` for progressive reading; `install` to download and extract for local use	references/skill.md
Register external tools	`toolbox create` to create a toolbox → `tool upload` to upload OpenAPI → `tool list` to get `tool_id` → `tool enable` to enable → `toolbox publish` to switch to published status	references/toolbox.md · references/tool.md

Read on demand: When you need complete parameters of subcommands or orchestration examples, read the corresponding reference files.

调用示例

Call Examples

/kweaver-core 列出所有知识网络
/kweaver-core 查看 Vega 健康状况
/kweaver-core 有哪些 Agent
/kweaver-core 跟 Agent xxx 对话，问他"今天库存情况"
/kweaver-core 搜索知识网络 xxx 中关于"供应链"的内容
/kweaver-core 用 dataview find 模糊搜索名字含 BOM 的数据视图
/kweaver-core 列出所有 dataflow
/kweaver-core 触发 dataflow 123，上传本地文件 ./demo.pdf
/kweaver-core 查看 dataflow 123 在 2026-04-01 的运行记录
/kweaver-core 查看 dataflow 123 的实例 456 日志，并展开 input output
/kweaver-core 列出所有 Agent 模板
/kweaver-core 基于 "数据分析助手" 模板创建一个新的 Agent
/kweaver-core 在 skill market 里查找名字包含 kweaver 的 skill
/kweaver-core 读取 skill xxx 的 SKILL.md 并保存到本地目录
/kweaver-core 创建一个名为 weather-svc 的 toolbox，对接 https://weather.example.com
/kweaver-core 把 ./openapi.json 上传到 toolbox 1234567890 并启用所有工具，最后发布

/kweaver-core List all knowledge networks
/kweaver-core Check Vega health status
/kweaver-core What Agents are there
/kweaver-core Converse with Agent xxx and ask "Today's inventory status"
/kweaver-core Search for content about "supply chain" in knowledge network xxx
/kweaver-core Use dataview find to fuzzy search data views whose names contain BOM
/kweaver-core List all dataflows
/kweaver-core Trigger dataflow 123 and upload local file ./demo.pdf
/kweaver-core View run records of dataflow 123 on 2026-04-01
/kweaver-core View logs of instance 456 of dataflow 123 and expand input output
/kweaver-core List all Agent templates
/kweaver-core Create a new Agent based on the "Data Analysis Assistant" template
/kweaver-core Search for skills containing kweaver in the skill market
/kweaver-core Read SKILL.md of skill xxx and save it to local directory
/kweaver-core Create a toolbox named weather-svc connected to https://weather.example.com
/kweaver-core Upload ./openapi.json to toolbox 1234567890, enable all tools, and finally publish

注意事项

Notes

不要自行猜测 business_domain 值。首次使用时运行
```
kweaver config show
```
或
```
kweaver config list-bd
```
确认当前 business domain。如果返回
```
bd_public (default)
```
但命令结果为空，可能需要用
```
kweaver config set-bd <uuid>
```
设置正确的值（也可用
```
config list-bd
```
从平台列出后再
```
set-bd
```
，或从平台 UI 请求头中获取
```
X-Business-Domain
```
）
Action 执行有副作用，执行前向用户确认
禁止运行
kweaver auth status
做预检。直接执行目标命令，CLI 会自动处理认证和 token 刷新
Token 1 小时过期。当
```
~/.kweaver/
```
中存在
```
refresh_token
```
（通过 OAuth2 登录获得）时，CLI 会自动刷新；遇到 401 错误时 CLI 会自动尝试刷新，刷新失败才提示用户重新运行
```
kweaver auth login <url>
```

Do not guess business_domain values. When using for the first time, run
```
kweaver config show
```
or
```
kweaver config list-bd
```
to confirm the current business domain. If it returns
```
bd_public (default)
```
but the command result is empty, you may need to use
```
kweaver config set-bd <uuid>
```
to set the correct value (you can also list from the platform with
```
config list-bd
```
then
```
set-bd
```
, or get
```
X-Business-Domain
```
from the platform UI request header)
Action execution has side effects, confirm with users before execution
Prohibited to run
kweaver auth status
for pre-check. Execute the target command directly, and the CLI will automatically handle authentication and token refresh
Token expires in 1 hour. When a
```
refresh_token
```
exists in
```
~/.kweaver/
```
(obtained via OAuth2 login), the CLI will automatically refresh; when encountering a 401 error, the CLI will automatically attempt to refresh, and only prompt the user to re-run
```
kweaver auth login <url>
```
if the refresh fails

查询策略（object-type query）

Query Strategy (object-type query)

调用

object-type query

时必须限制

limit

、用

search_after

分页、用

condition

过滤，避免宽表 JSON 截断。完整规则与示例见

references/bkn.md

。

When calling

object-type query

, you must limit

limit

, use

search_after

for pagination, and use

condition

for filtering to avoid wide table JSON truncation. Complete rules and examples can be found in

references/bkn.md