From cd955211e31f0e6f6c16b896121d9b2c1a9ed233 Mon Sep 17 00:00:00 2001 From: "zeyu.fz" Date: Mon, 17 Aug 2026 20:56:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(tool-bailian-kb):=20=E5=AE=8C=E5=96=84?= =?UTF-8?q?=E9=98=BF=E9=87=8C=E4=BA=91=E7=99=BE=E7=82=BC=E7=9F=A5=E8=AF=86?= =?UTF-8?q?=E5=BA=93=E7=AE=A1=E7=90=86=E6=96=87=E6=A1=A3=E4=B8=8E=E5=91=BD?= =?UTF-8?q?=E4=BB=A4=E5=8F=82=E8=80=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新技能描述，补充命令行工具 kscli 的使用范围与说明 - 细化安装与鉴权步骤，明确不同发行通道及 Node.js 版本要求 - 增加详细的命令用途对照表，便于用户区分不同操作命令 - 优化核心工作流示例，简化上传、建库、部署检索服务步骤 - 补充多种 ID 类型说明，帮助用户正确使用各类标识 - 添加关于危险和不可逆操作的说明及确认要求 - 强调服务版本状态及发布流程，规范草稿与发布版切换 - 新增详细的命令参考文档，覆盖 chunk、config、datacenter、 doc、kb、query、service 等命令组 - 更新 package 版本号至 0.1.5，标识本次文档与功能更新 --- packages/tool-bailian-kb/package.json | 2 +- .../skills/bailian-kb-management/SKILL.md | 80 +++++++-- .../bailian-kb-management/reference/chunk.md | 100 +++++++++++ .../bailian-kb-management/reference/config.md | 55 ++++++ .../reference/datacenter.md | 158 +++++++++++++++++ .../bailian-kb-management/reference/doc.md | 151 +++++++++++++++++ .../bailian-kb-management/reference/index.md | 73 ++++++++ .../bailian-kb-management/reference/kb.md | 137 +++++++++++++++ .../bailian-kb-management/reference/query.md | 58 +++++++ .../reference/service.md | 159 ++++++++++++++++++ 10 files changed, 961 insertions(+), 12 deletions(-) create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/chunk.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/config.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/datacenter.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/doc.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/index.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/kb.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/query.md create mode 100644 packages/tool-bailian-kb/skills/bailian-kb-management/reference/service.md diff --git a/packages/tool-bailian-kb/package.json b/packages/tool-bailian-kb/package.json index d6571e4..2f7c2aa 100644 --- a/packages/tool-bailian-kb/package.json +++ b/packages/tool-bailian-kb/package.json @@ -1,6 +1,6 @@ { "name": "@ali/bailian-kb-dsh", - "version": "0.1.4", + "version": "0.1.5", "description": "Bailian knowledge-base tools for DeepSeek Harness: kb_search and kb_chat over the DashScope RAG API, plus the kscli management skill.", "type": "module", "main": "lib/index.js", diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/SKILL.md b/packages/tool-bailian-kb/skills/bailian-kb-management/SKILL.md index b957183..0f3a4fb 100644 --- a/packages/tool-bailian-kb/skills/bailian-kb-management/SKILL.md +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/SKILL.md @@ -1,6 +1,12 @@ --- name: bailian-kb-management -description: 管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维）。当用户要创建/更新/删除知识库、上传或导入文档、部署检索服务、管理数据中心文件时使用 kscli。检索与问答不走本 skill——用原生工具 kb_search / kb_chat。 +description: >- + 管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维、数据中心文件管理），命令行工具为 kscli。 + 当用户要创建/更新/删除知识库、上传或导入文档（本地/OSS）、创建/部署/调参检索或问答服务、 + 增删改查 Chunk、管理数据中心类目/文件/集合时使用本 skill。 + 检索与问答不走本 skill——用原生工具 kb_search（取证据）/ kb_chat（成品问答）； + kscli search / chat 仅用于部署后的验证调试（如 --agent-version beta 调试草稿版）。 + 普通问答、编程、写作、翻译、泛搜索不触发本 skill。 --- # 百炼知识库管理（kscli） @@ -9,26 +15,78 @@ description: 管理阿里云百炼知识库（建库、上传文档、部署检 ## 前置检查 -1. `kscli --version` —— 未安装则运行 `npm install -g knowledge-studio-cli`（需 Node.js ≥ 18.17）；安装失败时把错误原样报告给用户，不要静默跳过。 +1. 安装校验：运行 `kscli kb list --help`。若报 `Unknown command` 或 kscli 未安装，执行 + `npm install -g knowledge-studio-cli@knowledge`（需 Node.js ≥ 18.17）。 + **管理命令（kb/doc/service/chunk/category/file/collection）只在 `knowledge` 发行通道； + `latest` 通道只有 search/chat/config，装错通道会导致所有管理命令不可用。** + 安装失败时把错误原样报告给用户，不要静默跳过。 2. 鉴权：需要 `DASHSCOPE_API_KEY`（环境变量，或 `kscli config set --key api_key --value sk-xxx`）。 3. workspace 解析优先级：`--workspace-id` 参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > `kscli config set --key workspace_id --value ws-xxx`。 -## 常用工作流：建库到可检索 +## 何时用哪个命令 + +| 用户意图 | 命令 | 备注 | +| --- | --- | --- | +| 查知识 / 问答（日常检索） | 原生工具 `kb_search` / `kb_chat` | 不走 kscli | +| 建库 / 查看 / 改名 / 删库 / 监控 | `kscli kb create/list/info/update/delete/stats` | [reference/kb.md](reference/kb.md) | +| 上传本地文档、看解析状态、删文档、打标签 | `kscli doc upload/list/status/delete/tag` | [reference/doc.md](reference/doc.md) | +| 从 OSS 批量导入 | `kscli doc import-oss` | Bucket 需预先授权服务角色 | +| 创建 / 部署 / 调参检索（问答）服务 | `kscli service create/update/deploy/…` | [reference/service.md](reference/service.md) | +| 修正错误切片、屏蔽某段内容 | `kscli chunk add/list/update/delete` | [reference/chunk.md](reference/chunk.md) | +| 数据中心类目 / 文件 / 集合管理 | `kscli category/file/collection …` | [reference/datacenter.md](reference/datacenter.md) | +| CLI 配置、升级 | `kscli config show/set`、`kscli update` | [reference/config.md](reference/config.md) | +| 部署后验证、调试草稿版服务 | `kscli search/chat --agent-version beta` | [reference/query.md](reference/query.md) | + +## 核心工作流：建库到可检索 ```bash -kscli kb create --name "my-kb" --embedding-model text-embedding-v3 # 1. 建库 -kscli doc upload --kb-id --file ./docs.pdf # 2. 上传本地文档 -kscli doc status --kb-id --doc-id # 3. 轮询至 COMPLETED -kscli service create ... && kscli service deploy ... # 4. 建/部署检索服务 → 得到 agent_id +kscli doc upload --file ./docs/ --workspace-id ws-xxx # 1. 上传本地文件/目录 → 得 fileId +kscli kb create --name my-kb --doc-id --wait # 2. 建库并导入 → 得 index-id (pipelineId) +kscli service create --name my-search --scene search --index-id # 3. 建检索服务 → 得 agent-id（draft） +kscli service deploy --agent-id --yes # 4. 发布服务（此后可被默认版本调用） +kscli service list --scene search --status deployed # 5. 确认服务可见 ``` -部署完成后用 `kscli service list` 确认服务可见，再用 `kb_search` 带该 `agent_id` 验证检索。 +部署完成后用原生工具 `kb_search` 带该 `agent_id` 验证检索；若要在部署前调试草稿配置，用 `kscli search --agent-id --agent-version beta`。 -## 命令组速查 +已有文件再入库的简写：`kscli doc upload --file ./a.md --index-id --wait`（上传+导入一步完成）。 -`kb`（list/info/create/update/delete/stats）· `doc`（list/upload/status/delete/tag/import-oss）· `service`（list/get/create/update/deploy/delete/copy）· `chunk`（add/list/update/delete）· `file` / `collection` / `category`（数据中心）。全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`。完整手册：https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md +## ID 速查（极易混淆） + +| ID | 来源 | 用在哪 | +| --- | --- | --- | +| `index-id` | `kb create` 返回的 pipelineId / `kb list` | 所有 kb/doc/chunk 命令的 `--index-id` | +| `fileId` | `doc upload` / `doc import-oss` 返回 | 数据中心命令（`file get/delete`、`kb create --doc-id`、`doc tag`） | +| `doc_id`（库内文档 ID） | `doc list` 输出 | `doc delete`、`chunk add/update` 的 `--doc-id`；**可能带 workspace 后缀，≠ fileId** | +| `job-id` | 导入命令返回的 ingestionId | `doc status`（必须同时给 `--index-id` 和 `--job-id`） | +| chunk id | `chunk list` 输出的 `metadata._id` | `chunk update/delete` 的 `--chunk-id` | +| `agent-id` | `service create/list` | `service *`、`kb_search`/`kb_chat`、`kscli search/chat` | + +## 命令参考（权威） + +命令的完整 Usage / Flags / Notes / Examples 在 [`reference/`](reference/index.md)： + +- [reference/index.md](reference/index.md) — 全命令速查表、全局 flag、鉴权说明 +- reference/<group>.md — 按命令组分文件（kb / doc / service / chunk / datacenter / config / query） + +执行不熟悉的命令前，先读对应 reference 或跑 `kscli <命令> --help`。**不要猜 flag。** +全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`、`--verbose`。 + +## 危险与不可逆操作 + +执行以下操作前须向用户确认，脚本化时才用 `--yes` 跳过交互确认： + +- `kb delete`：不可逆，库和全部索引内容永久删除（数据中心源文件保留）。 +- `file delete`：不可逆，且引用该文件的知识库文档索引会失效；只想从单个库移除用 `doc delete`。 +- `chunk delete`：不可逆。 +- `service deploy`：发布影响线上调用方；`service delete` 后 agent_id 不可再用（软删、幂等）。 +- `collection create`：**没有删除 API**，创建集合要慎重。 +- 索引配置（embedding 模型、chunk size 等）建库后不可改，只能重建。 ## 最佳实践 - 用户反复使用同一检索服务时，建议其把 agent_id 写入项目指令（如 AGENTS.md）或让 agent 记住，后续 kb_search / kb_chat 直接携带。 -- 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用；draft 调试用 `--agent-version beta`。 +- 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用；draft 调试用 `--agent-version beta`。改已发布版本的配置：先改 beta 草稿（`service update`），验证后 `service deploy` 发新版本。 +- 导入类命令（`kb create`、`doc upload --index-id`、`doc status`）优先带 `--wait` 轮询到终态，避免手工轮询；文档解析失败（如 PARSE_FAILED）会以非零退出码透传错误。 +- `chunk add` 有 10 QPS 限流，批量脚本注意节流；响应不带 chunk id，需要 `chunk list` 反查。 +- `service list` 必须带 `--scene chat|search`，两个场景要分别查询。 diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/chunk.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/chunk.md new file mode 100644 index 0000000..d5aa944 --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/chunk.md @@ -0,0 +1,100 @@ +# `kscli chunk` — Chunk 运维 + +> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。 +> chunk id = `chunk list` 输出的 `metadata._id`；文档 id = `metadata.doc_id`。 + +## `kscli chunk add` + +直接向库内添加 chunk。 + +``` +Usage: kscli chunk add --index-id (--content | --field ) [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--doc-id ` | 归属文档 ID（取自 `doc list`）；**实践中所有库类型都必填** | +| `--content ` | Chunk 正文，≤6000 字符（文档型库）；与 `--content-file` 二选一 | +| `--content-file ` | 从 UTF-8 纯文本文件读正文（.md/.txt 等） | +| `--title ` | Chunk 标题，≤50 字符 | +| `--image-url ` | Chunk 图片 URL（可重复，≤10 个） | +| `--field ` | 表格/图片型库的任意字段（可重复，key 为 Excel 列头）；与 content/title/image 互斥 | + +Notes： + +- 支持文档/表格/图片型知识库；音视频型不支持。 +- `--doc-id` 用 `doc list` 的文档级 id；`chunk list` 输出里的行级 doc_id 不被接受。 +- 图片型文档不支持文本 chunk，需指向文本型文档（docx/pdf/txt）。 +- API 幂等但限流 10 QPS——批量脚本注意节流。 +- 响应不带 chunk id；添加后用 `chunk list` 反查。 + +```bash +kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --doc-id file-xxx +kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2 +``` + +## `kscli chunk list` + +列出 chunk 内容与状态。 + +``` +Usage: kscli chunk list --index-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--doc-id ` | 只看该文档的 chunk | +| `--page-number ` / `--page-size ` | 分页（服务端默认 20，上限 100） | + +Notes： + +- 后续 update/delete 用输出中的 `metadata._id`（chunk id）与 `metadata.doc_id`（文档 id）。 + +```bash +kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50 +``` + +## `kscli chunk update` + +改 chunk 内容或切换检索可见性。 + +``` +Usage: kscli chunk update --index-id --chunk-id --doc-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--chunk-id ` | Chunk ID（`chunk list` 的 `metadata._id`） | +| `--doc-id ` | 归属文档 ID（`chunk list` 的 `metadata.doc_id`） | +| `--content ` | 新内容，10-6000 字符；与 `--content-file` 二选一 | +| `--content-file ` | 从 UTF-8 纯文本文件读新内容 | +| `--title ` | 标题，0-50 字符（空串清除；省略保持不变） | +| `--exclude` / `--include` | 从检索中排除 / 恢复（默认 include） | + +Notes： + +- 内容须在 10-6000 字符且不超过库的最大 chunk size。 +- `--content-file` 只接受纯文本；.docx/.pdf 不在这里解析。 +- 只切 `--exclude/--include` 不给新内容时，自动重提交现有内容。 + +```bash +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" +kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude +``` + +## `kscli chunk delete` + +删除 chunk。**不可逆，执行前须向用户确认。** + +``` +Usage: kscli chunk delete --index-id --chunk-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--chunk-id ` | 要删的 chunk ID（可重复；超过 10 个自动分批发送） | +| `--yes` | 跳过交互确认 | + +```bash +kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes +``` diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/config.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/config.md new file mode 100644 index 0000000..c48c2a1 --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/config.md @@ -0,0 +1,55 @@ +# `kscli config` / `update` — 配置与升级 + +> 通用全局 flag 见 [index.md](index.md)。这两组命令无需鉴权。 + +## `kscli config show` + +显示当前配置。 + +``` +Usage: kscli config show +``` + +```bash +kscli config show +kscli config show --output json +``` + +## `kscli config set` + +设置配置项。 + +``` +Usage: kscli config set --key --value +``` + +可用 key：`base_url`、`output`、`output_dir`、`timeout`、`api_key`、`access_token`、 +`access_key_id`、`access_key_secret`、`security_token`、`default_*_model`、`workspace_id`。 + +```bash +kscli config set --key workspace_id --value ws-xxx +kscli config set --key output --value json +kscli config set --key timeout --value 600 +``` + +## `kscli update` + +升级 CLI 到最新或指定版本。 + +``` +Usage: kscli update [--to ] +``` + +| Flag | 说明 | +| --- | --- | +| `--to ` | 安装该精确版本而非最新版 | + +Notes： + +- 管理命令在 `knowledge` 发行通道；若 `kscli update` 后管理命令消失（升到了 latest），用 + `npm install -g knowledge-studio-cli@knowledge` 装回。 + +```bash +kscli update +kscli update --to 0.1.14 +``` diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/datacenter.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/datacenter.md new file mode 100644 index 0000000..8f88a49 --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/datacenter.md @@ -0,0 +1,158 @@ +# `kscli category` / `file` / `collection` — 数据中心 + +> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。 +> 数据中心是文件的原始存储层：collection（集合）> category（类目）> file（文件）。知识库只是索引层，删库不影响这里的文件。 + +## `kscli category list` + +列出数据中心类目。 + +``` +Usage: kscli category list [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--collection-id ` | 按集合 ID 精确过滤 | +| `--parent-id ` | 列出该父类目下的子类目 | +| `--name ` | 按名称过滤（**精确匹配**，与 kb list 的模糊匹配不同） | +| `--next-token ` | 游标分页（取自上一页输出） | +| `--max-result ` | 每页条数（默认 20） | + +Notes： + +- 标 `[default]` 的类目是未指定类目时文件的默认落点。 + +```bash +kscli category list --workspace-id ws-xxx +kscli category list --name my-category +``` + +## `kscli category add` + +创建数据中心类目。 + +``` +Usage: kscli category add --name [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--name ` | 类目名（1-20 字符） | +| `--parent-id ` | 作为该类目的子类目创建 | +| `--collection-id ` | 建在该集合下（默认平台集合） | + +```bash +kscli category add --name product-docs --workspace-id ws-xxx +kscli category add --name sub --parent-id cate-xxx +``` + +## `kscli category delete` + +删除数据中心类目。**执行前须向用户确认。** + +``` +Usage: kscli category delete --category-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--yes` | 跳过交互确认 | + +Notes： + +- 含文件或子类目时的行为由服务端决定——服务端错误原样透传。 + +```bash +kscli category delete --category-id cate-xxx --yes +``` + +## `kscli file list` + +列出类目下的文件。 + +``` +Usage: kscli file list --category-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--category-id ` | 必须是真实类目 id（通过 `category list` 查）；精确匹配 | +| `--name ` | 按**不含扩展名的完整文件名**精确过滤（a.md → 传 a）；部分关键词查不到 | +| `--file-id ` | 按文件 ID 精确过滤（可重复） | +| `--next-token ` / `--max-result ` | 游标分页 | + +```bash +kscli file list --category-id cate-xxx --workspace-id ws-xxx +kscli file list --category-id cate-xxx --name report +``` + +## `kscli file get` + +查看文件详情（大小、MD5、标签、时间戳）。 + +``` +Usage: kscli file get --file-id [flags] +``` + +```bash +kscli file get --file-id file-xxx --workspace-id ws-xxx +``` + +## `kscli file delete` + +永久删除数据中心文件。**不可逆，执行前须向用户确认。** + +``` +Usage: kscli file delete --file-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--yes` | 跳过交互确认 | + +Notes： + +- 不可逆。引用该文件的知识库文档索引会失效。 +- 只想从单个知识库移除文档时用 `doc delete`。 + +```bash +kscli file delete --file-id file-xxx --yes +``` + +## `kscli collection create` + +创建 FILE 数据集合。**没有删除 API——创建须慎重，执行前须向用户确认。** + +``` +Usage: kscli collection create --name --description [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--name ` | 集合名 | +| `--description ` | 描述（服务端必填） | +| `--store-type ` | 存储：platform（托管，默认）或 custom（自有 OSS bucket） | +| `--oss-region ` / `--oss-bucket ` | `--store-type custom` 时必填 | + +Notes： + +- 自有 bucket 必须带标签 `bailian-connector-access=ReadAndWrite`（百炼基于标签的访问控制）；缺失时服务端会以有误导性的 “setBucketCORS failed” 报错拒绝创建。 + +```bash +kscli collection create --name my-collection --description 'team docs' --workspace-id ws-xxx +kscli collection create --name oss-coll --description 'own bucket' --store-type custom --oss-region cn-beijing --oss-bucket my-bucket +``` + +## `kscli collection get` + +查看数据集合详情。 + +``` +Usage: kscli collection get (--collection-id | --name ) [flags] +``` + +```bash +kscli collection get --collection-id conn-xxx --workspace-id ws-xxx +kscli collection get --name my-collection +``` diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/doc.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/doc.md new file mode 100644 index 0000000..8d1d1ae --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/doc.md @@ -0,0 +1,151 @@ +# `kscli doc` — 文档上传与导入 + +> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。 + +## `kscli doc upload` + +上传本地文件/目录到数据中心，可选同时导入知识库。 + +``` +Usage: kscli doc upload --file [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--file ` | 本地文件或目录（可重复）。目录递归扫描，不支持的格式自动跳过 | +| `--index-id ` | 注册后同时导入该知识库（所有文件合并为一个导入任务） | +| `--category-id ` | 目标数据中心类目；默认 workspace 默认类目 | +| `--tag ` | 文件标签（可重复），应用到每个上传文件 | +| `--wait` | 轮询导入任务到终态（需配合 `--index-id`） | +| `--poll-interval ` | 轮询间隔（默认 5） | + +Notes： + +- 流水线：申请上传租约 → PUT 到 OSS → 注册文件 →（带 `--index-id` 时）创建导入任务。 +- 目录递归扫描时自动跳过 node_modules、.git 等。 +- 多文件顺序处理；中途失败时，已注册的 fileId 会列在错误提示里。 + +```bash +kscli doc upload --file ./a.md --workspace-id ws-xxx +kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait +kscli doc upload --file ./docs/ --dry-run --verbose +``` + +## `kscli doc list` + +列出库内文档及解析/索引状态。 + +``` +Usage: kscli doc list --index-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--page-number ` | 页码（默认 1） | +| `--page-size ` | 每页条数（服务端默认 10，上限 100） | + +Notes： + +- FAILED 状态的文档在 text 模式下高亮；用 `doc status` 查失败原因。 +- 输出的 doc_id 才是 `doc delete` / `chunk add` 应使用的文档 ID。 + +```bash +kscli doc list --index-id idx-xxx --workspace-id ws-xxx +kscli doc list --index-id idx-xxx --page-size 100 +``` + +## `kscli doc status` + +查看导入任务状态。 + +``` +Usage: kscli doc status --index-id --job-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--job-id ` | 导入任务 ID（导入命令返回的 ingestionId） | +| `--wait` | 轮询到终态 | +| `--poll-interval ` | 轮询间隔（默认 5） | + +Notes： + +- `--index-id` 和 `--job-id` 缺一不可（只传一个返回 SystemError）。 +- 任务整体状态：PENDING / RUNNING / COMPLETED；单文档失败（如 PARSE_FAILED）以非零退出码透传错误。 + +```bash +kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10 +``` + +## `kscli doc delete` + +从库中删除文档及其 chunk。**执行前须向用户确认。** + +``` +Usage: kscli doc delete --index-id --doc-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--doc-id ` | 要删除的文档 ID（可重复） | +| `--yes` | 跳过交互确认 | + +Notes： + +- 只从知识库索引移除，数据中心源文件保留。 +- **用 `doc list` 输出的 doc_id，不是 `doc upload` 返回的 fileId**：经 `kb create --doc-id` 入库的文档二者相等；经 `doc upload --index-id` 入库的 doc_id 可能带 workspace 后缀。 +- 删除传播最多 ~30s，期间文档可能仍出现在 doc list 里。 + +```bash +kscli doc delete --index-id idx-xxx --doc-id file-a --doc-id file-b --yes +``` + +## `kscli doc tag` + +批量更新数据中心文件标签。 + +``` +Usage: kscli doc tag --doc-id --tag [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--doc-id ` | 数据中心文件 ID（可重复，每次 1-20 个） | +| `--tag ` | 应用到每个 `--doc-id` 的标签（可重复，单个 ≤32 字符） | +| `--mode ` | 更新模式：append（默认）或 overwrite | + +Notes： + +- 同一批标签应用到所有 `--doc-id`；不同标签集要分多次执行。 +- 服务端限制：每文件 ≤100 个标签，标签总长 ≤700 字符。 + +```bash +kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx +kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite +``` + +## `kscli doc import-oss` + +从已授权 OSS bucket 批量导入到数据中心。 + +``` +Usage: kscli doc import-oss --bucket --region --oss-key [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--bucket ` | 已授权的 OSS bucket | +| `--region ` | OSS region（如 cn-beijing） | +| `--oss-key ` | 要导入的 OSS object key（可重复，每次 1-10 个） | +| `--overwrite` | 覆盖之前导入的同名文件 | + +Notes： + +- Bucket 须预先授权给平台服务角色；权限错误会透传，并提示检查 RAM 控制台的 AliyunServiceRoleForBailian。 +- 文件名取 OSS key 的 basename。 +- `--overwrite` 会替换旧文件并签发**新的 fileId**（旧 fileId 失效）。 + +```bash +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx +kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite +``` diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/index.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/index.md new file mode 100644 index 0000000..8ad6400 --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/index.md @@ -0,0 +1,73 @@ +# `kscli` 命令参考索引 + +> 由 `knowledge-studio-cli@knowledge`（0.0.0-beta-4086da5-202608141600）各命令 `--help` 输出整理。 +> 命令详情在同目录 `.md`；本索引只放速查表、全局 flag 与鉴权说明。 +> 版本更新后以 `kscli <命令> --help` 为准。 + +## 速查表 + +| 命令 | 鉴权 | 说明 | 详情 | +| --- | --- | --- | --- | +| `kscli kb list` | API Key | 列出 workspace 内知识库 | [kb.md](kb.md) | +| `kscli kb info` | API Key | 查看知识库配置详情 | [kb.md](kb.md) | +| `kscli kb create` | API Key | 建库并导入数据中心文件或类目 | [kb.md](kb.md) | +| `kscli kb update` | API Key | 改名、描述或 rerank 阈值 | [kb.md](kb.md) | +| `kscli kb delete` | API Key | 删库（含全部文档与 chunk，不可逆） | [kb.md](kb.md) | +| `kscli kb stats` | API Key | 存储量与 QPS 监控数据 | [kb.md](kb.md) | +| `kscli doc list` | API Key | 列出库内文档及解析/索引状态 | [doc.md](doc.md) | +| `kscli doc status` | API Key | 查看导入任务状态 | [doc.md](doc.md) | +| `kscli doc upload` | API Key | 上传本地文件/目录，可选同时入库 | [doc.md](doc.md) | +| `kscli doc delete` | API Key | 从库中删除文档及其 chunk | [doc.md](doc.md) | +| `kscli doc tag` | API Key | 批量更新数据中心文件标签 | [doc.md](doc.md) | +| `kscli doc import-oss` | API Key | 从已授权 OSS bucket 批量导入 | [doc.md](doc.md) | +| `kscli service list` | API Key | 列出检索/问答服务 | [service.md](service.md) | +| `kscli service get` | API Key | 查看服务各版本配置 | [service.md](service.md) | +| `kscli service create` | API Key | 创建服务（初始为 draft/beta） | [service.md](service.md) | +| `kscli service update` | API Key | 更新名称、描述或草稿配置 | [service.md](service.md) | +| `kscli service deploy` | API Key | 把 beta 草稿发布为新版本 | [service.md](service.md) | +| `kscli service delete` | API Key | 删除服务（软删、幂等） | [service.md](service.md) | +| `kscli service copy` | API Key | 复制服务为新草稿（名称加 copy\_ 前缀） | [service.md](service.md) | +| `kscli chunk add` | API Key | 直接向库内添加 chunk | [chunk.md](chunk.md) | +| `kscli chunk list` | API Key | 列出 chunk 内容与状态 | [chunk.md](chunk.md) | +| `kscli chunk update` | API Key | 改 chunk 内容或切换检索可见性 | [chunk.md](chunk.md) | +| `kscli chunk delete` | API Key | 删除 chunk（不可逆） | [chunk.md](chunk.md) | +| `kscli category list` | API Key | 列出数据中心类目 | [datacenter.md](datacenter.md) | +| `kscli category add` | API Key | 创建数据中心类目 | [datacenter.md](datacenter.md) | +| `kscli category delete` | API Key | 删除数据中心类目 | [datacenter.md](datacenter.md) | +| `kscli file list` | API Key | 列出类目下的文件 | [datacenter.md](datacenter.md) | +| `kscli file get` | API Key | 查看文件详情（大小/MD5/标签/时间） | [datacenter.md](datacenter.md) | +| `kscli file delete` | API Key | 永久删除数据中心文件 | [datacenter.md](datacenter.md) | +| `kscli collection create` | API Key | 创建 FILE 数据集合（无删除 API） | [datacenter.md](datacenter.md) | +| `kscli collection get` | API Key | 查看数据集合详情 | [datacenter.md](datacenter.md) | +| `kscli config show` | 无需 | 显示当前配置 | [config.md](config.md) | +| `kscli config set` | 无需 | 设置配置项 | [config.md](config.md) | +| `kscli update` | 无需 | 升级 CLI | [config.md](config.md) | +| `kscli search` | API Key | RAG 语义检索（部署验证用；日常检索走原生工具 kb_search） | [query.md](query.md) | +| `kscli chat` | API Key | RAG 问答，SSE 流式（部署验证用；日常问答走原生工具 kb_chat） | [query.md](query.md) | +| `kscli retrieve` | API Key | 已废弃，改用 `search` | [query.md](query.md) | + +## 全局 flag（所有命令可用） + +| Flag | 说明 | +| --- | --- | +| `--output ` | 输出格式：text、json | +| `--timeout ` | 请求超时 | +| `--quiet` | 抑制非必要输出 | +| `--verbose` | 打印 HTTP 请求/响应详情 | +| `--dry-run` | 只预览请求不执行 | +| `--config ` | 本次命令使用指定配置 profile | +| `--help` / `--version` | 帮助 / 版本 | + +## 鉴权 flag（API Key 类命令可用） + +| Flag | 说明 | +| --- | --- | +| `--api-key ` | API key（优先于环境变量 `DASHSCOPE_API_KEY` 与 config） | +| `--base-url ` | API base URL | +| `--workspace-id ` | Workspace ID（或环境变量 `BAILIAN_WORKSPACE_ID`，或 config `workspace_id`） | + +## 说明 + +- 所有管理命令使用 DashScope API Key（Bearer token）鉴权，无 console 登录态。 +- 默认输出为 text；agent 解析结果时建议显式加 `--output json`。 +- 分页有两种风格：kb/doc/service/chunk 用 `--page-number/--page-size`（page-size 上限 100）；category/file 用游标 `--next-token/--max-result`。 diff --git a/packages/tool-bailian-kb/skills/bailian-kb-management/reference/kb.md b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/kb.md new file mode 100644 index 0000000..191e8be --- /dev/null +++ b/packages/tool-bailian-kb/skills/bailian-kb-management/reference/kb.md @@ -0,0 +1,137 @@ +# `kscli kb` — 知识库生命周期 + +> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。 + +## `kscli kb list` + +列出 workspace 内知识库。 + +``` +Usage: kscli kb list [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--name ` | 按名称过滤（模糊匹配，1-20 字符） | +| `--page-number ` | 页码（默认 1） | +| `--page-size ` | 每页条数 | + +Notes： + +- 返回的 id 即后续 kb/doc/chunk 管理命令的 `--index-id`。 + +```bash +kscli kb list --workspace-id ws-xxx +kscli kb list --name demo --page-number 2 --page-size 50 +``` + +## `kscli kb info` + +查看知识库配置详情。 + +``` +Usage: kscli kb info --index-id [flags] +``` + +Notes： + +- 索引配置不可变，改配置需重建知识库。 + +```bash +kscli kb info --index-id idx-xxx --workspace-id ws-xxx +``` + +## `kscli kb create` + +建库并导入数据中心文件或类目。 + +``` +Usage: kscli kb create --name (--doc-id | --category-id ) [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--name ` | 库名（1-20 字符，workspace 内唯一） | +| `--doc-id ` | 数据中心文件 id（可重复）；与 `--category-id` 互斥 | +| `--category-id ` | 导入该类目下所有文件（可重复）；与 `--doc-id` 互斥 | +| `--embedding-model ` | Embedding 模型（默认 text-embedding-v4） | +| `--chunk-size ` | Chunk 大小（默认 600，建议 300-800） | +| `--wait` | 轮询首次导入任务到终态 | +| `--poll-interval ` | 轮询间隔（默认 5） | + +Notes： + +- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。 +- 返回知识库 id（pipelineId）与首次导入任务 id（ingestionId）；用 `doc status`（或 `--wait`）跟踪导入。 + +```bash +kscli kb create --name demo --doc-id file-xxx --workspace-id ws-xxx +kscli kb create --name demo --category-id cate-xxx --wait +``` + +## `kscli kb update` + +改名、描述或 rerank 阈值。 + +``` +Usage: kscli kb update --index-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--name ` | 新库名（1-20 字符） | +| `--description ` | 新描述 | +| `--rerank-min-score ` | Rerank 最低分阈值，0-1（低于该分的 chunk 被过滤） | + +Notes： + +- 索引配置（embedding 模型、chunk size 等）不可变——要改只能重建。 + +```bash +kscli kb update --index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx +kscli kb update --index-id idx-xxx --rerank-min-score 0.3 +``` + +## `kscli kb delete` + +删库（含全部文档与 chunk）。**不可逆，执行前须向用户确认。** + +``` +Usage: kscli kb delete --index-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--yes` | 跳过交互确认 | + +Notes： + +- 不可逆——知识库与全部索引内容永久删除。 +- 数据中心内的源文件不受影响，只删索引。 + +```bash +kscli kb delete --index-id idx-xxx --workspace-id ws-xxx +kscli kb delete --index-id idx-xxx --yes +``` + +## `kscli kb stats` + +存储量与 QPS 监控数据。 + +``` +Usage: kscli kb stats --index-id [flags] +``` + +| Flag | 说明 | +| --- | --- | +| `--start