kweaver-core - SKILL.md Agent Skill

name: kweaver-core description: >- 操作 KWeaver 知识网络与 Decision Agent — 构建知识网络、查询 Schema/实例、语义搜索、执行 Action、Agent CRUD 与对话、Trace 数据分析。操作 Dataflow 文档流程 — 列出流程、触发运行、查询运行历史、查看步骤日志。操作 Skill 管理模块 — 注册 Skill、市场查找、渐进式读取、下载与安装。操作 Toolbox / Tool — 创建工具箱、上传 OpenAPI 工具、发布与启停。操作 Vega 可观测平台 — 查询 Catalog/资源/连接器类型、健康巡检。操作模型工厂 — 大模型/小模型 CRUD（mf-model-manager）、OpenAI 兼容对话与小模型调用（mf-model-api）、adapter 注册。当用户提到"知识网络"、"知识图谱"、"查询对象类"、 "执行 Action"、"有哪些 Agent"、"创建 Agent"、"跟 Agent 对话"、"列出所有 Agent 模板"、"列出我创建的Agent"、 "列出私人空间的Agent"、"dataflow"、"数据流"、"流程编排"、"流程运行记录"、"流程日志"、 "触发 dataflow"、"查看 dataflow 运行历史"、"Skill"、"技能包"、"注册 Skill"、"安装 Skill"、"读取 SKILL.md"、 "toolbox"、"工具箱"、"上传工具"、"注册工具"、"OpenAPI 工具"、"启用工具"、"发布 toolbox"、 "数据源"、"数据视图"、"原子视图"、"Catalog"、"Vega"、 "健康检查"、"巡检"、"trace"、"证据链"、"数据流追踪"、"数据来源"、"数据怎么得到的"、 "BKN 指标"、"指标管理"、"指标查询"、"指标试算"、"metric dry-run"、"模型工厂"、"小模型"、"embedding"、"rerank"、"mf-model"、"model chat" 等意图时自动使用。 allowed-tools: Bash(kweaver ), Bash(npx kweaver ) argument-hint: [自然语言指令]

KWeaver CLI

KWeaver 平台的命令行工具，覆盖认证、平台业务域（config）、知识网络管理与查询、Agent CRUD 与对话、数据源管理。

安装

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

需 Node.js 22+。也可用 npx kweaver 临时运行。

使用方式

kweaver [--base-url <url>] [--token <access-token>] [--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。

使用前提

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

认证优先级

CLI 全局 --token + --base-url（或已有 KWEAVER_BASE_URL / active platform）→ Stateless flag 模式（一次性传 token，本次调用不读写 ~/.kweaver/；token 过期不会自动续期；不能用 auth login / logout 等会修改本地凭据的命令）
KWEAVER_TOKEN + KWEAVER_BASE_URL 环境变量 → 静态 Token（如存在则优先使用，不会用 refresh 换发）
~/.kweaver/ 凭据（kweaver auth login 写入）→ 默认用 refresh_token 换发 access_token（推荐）
KWEAVER_USER 环境变量（或全局 --user 参数）→ 使用指定用户的凭证，不切换活跃用户

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

KWEAVER_BUSINESS_DOMAIN 环境变量
当前平台 config.json 中的 businessDomain（kweaver config set-bd）
默认 bd_public（首次登录后 CLI 可能已自动写入更合适的值）

命令组总览

命令组	说明	常用命令	详细参考
`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/vega 操作）	`config show`, `config list-bd`, `config set-bd <uuid>`	`references/config.md`
`bkn`	BKN 知识网络管理、Schema、查询、Action、指标	`bkn validate`/`push` 默认检测 `.bkn` 编码；`bkn metric` 管理/查询 BKN 指标与指标数据/试算，见 `references/metric.md`；其余见 `references/bkn.md`	`references/bkn.md`, `references/metric.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> [--view tree\|perf\|evidence\|reasoning\|all] [--full] [--json]`	`references/agent.md`
~~`ds`~~	已移除（CLI）；数据连接迁到 `vega catalog`，CSV 流程合并进 `bkn create-from-csv`。SDK 仍保留 `client.datasources` 作 deprecated 兼容层。	`vega catalog list/get/create/discover/resources/delete`、`bkn create-from-csv`	`references/ds.md`、`references/vega.md`
`resource`	vega-backend 资源（table / logicview）	`resource list`、`find --name`、`get`、`query`、`delete`；BKN 绑定用 type=resource	`references/resource.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`
`model`	模型工厂（mf-model-manager + mf-model-api）	`model llm`、`model small`、`model llm chat`、`model small embeddings` / `model small rerank`；大模型 `model_type`：`llm` / `rlm` / `vu`（见 `references/model.md`）；离线模版：`model llm --template` / `model small --template`	`references/model.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）；`execute`/`debug` 支持 `--path` 注入 `{param}`	`tool upload --toolbox <id> <openapi-spec>`、`tool list --toolbox <id>`、`tool enable/disable --toolbox <id> <tool-id>...`、`tool debug --toolbox <id> <tool-id> --path '{"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 --help`, `context-loader <subcommand> --help`, `context-loader search-schema <kn-id> <query>`（也支持 `--kn-id <id>` flag；省略时回退到 deprecated 的 `context-loader config`）	`references/context-loader.md`
`call`	通用 API 调用	`call <url> [-X POST] [-d '...']`（可用 `curl` 别名；支持 `--url`、`--data-raw` 等，见 `kweaver --help`）	`references/call.md`

操作指南

场景	说明	详细参考
登录后确认业务域	`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、resource query 等	references/troubleshooting.md
列/查 vega-backend 资源	`list` 浏览；`find --name` 按名搜索（`--exact`/`--wait`）；`query` 分页取数据行	references/resource.md
管理 Dataflow 文档流程	`list` 看 DAG；`run` 触发本地文件或远程 URL；`runs --since` 看自然日运行记录；`logs --detail` 查步骤载荷	references/dataflow.md
模型工厂 / 小模型 adapter	TS CLI：`model llm	small …`、`model llm chat`、`model small embeddings`/`model small rerank`；Python SDK：`client.models`（CRUD/test +` invocation.chat`/`embedding`/`rerank`）；`--adapter-code-file`注册 Python`main` 适配器
Python SDK（应用代码）	使用 PyPI `kweaver-sdk`：`KWeaverClient`、认证、分页与排障；与 CLI/MCP 接入指南互补	docs/guides/python-sdk-guide.md · 中文版
Trace 数据分析	`agent trace <cid> --view tree\|perf\|evidence\|reasoning\|all`：SDK 已内置四视图（调用拓扑 / 性能拆解 / 工具命中证据链 / LLM 推理过程），不再需要手工拼。`--full` 关掉每条消息的截断；`--json` 拿原始 spans。	`references/agent.md`
管理 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 文件。

调用示例

/kweaver-core 列出所有知识网络
/kweaver-core 查看 Vega 健康状况
/kweaver-core 有哪些 Agent
/kweaver-core 跟 Agent xxx 对话，问他"今天库存情况"
/kweaver-core 搜索知识网络 xxx 中关于"供应链"的内容
/kweaver-core 用 resource 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 并启用所有工具，最后发布

注意事项

不要自行猜测 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>

查询策略（object-type query）

调用 object-type query 时必须限制 limit、用 search_after 分页、用 condition 过滤，避免宽表 JSON 截断。完整规则与示例见 references/bkn.md。