Skip to content

Commit c4ce767

Browse files
clark-fcclark-fc
committed
feat(knowledge): unify terminology and enhance documentation for data sets
- Standardized terminology across documentation to refer to "data sets" instead of "collections" for consistency. - Updated various command descriptions and documentation sections to reflect the new terminology. - Added detailed notes on the handling of personal knowledge bases and the structure of data sets. - Ensured clarity in command usage and examples, particularly regarding the creation and management of data sets. - Introduced a new section on personal data binding and maintenance processes to improve user guidance.
1 parent bef0908 commit c4ce767

20 files changed

Lines changed: 292 additions & 135 deletions

File tree

‎docs/agents/skill-change.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,9 @@ bailian-gen bailian-finetune bailian-managed-agent bailian-web-search
4848

4949
### B. 文案与落款一致性
5050

51+
- [ ] 知识库用户可见术语统一为「数据集（collection）」；服务端原始字段、API 路径和必需标签保留协议名称。
52+
- [ ] 个人知识库 Skill 的手写流程放在 `references/`，命令生成物仍在 `reference/`；本地绑定属于 Skill 文件协议，不伪装成 CLI 配置。验证自然语言发现、跨会话范围复用、当前附件不建库、暂停和失败恢复；纯文本模拟不等同于真实宿主行为验证。
53+
5154
- [ ] 领域 skill（gen / finetune / managed-agent）路由或命令表后有指向 `reference/` 的句；文末 `## references`（protocol + reference）与家族对齐
5255
- [ ] description 含 WHAT + WHEN + 反触发；安装说明指向 `bl skill init`，不写 companions 必装
5356
- [ ] Quick examples 只演示本 skill 职责（hub 不示范 `bl image` / `bl video` 等）

‎docs/knowledge/collection-category.md‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# 数据中心集合与分类命令手册
1+
# 数据中心数据集与分类命令手册
22

3-
集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
3+
数据集（collection）是数据中心的顶层容器。分类（category）用于组织数据集内的文件，支持多级嵌套。
44

55
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](knowledge-cli-guide.md#通用约定)。
66
77
---
88

99
#### `bl knowledge collection create`
1010

11-
创建 FILE 数据集合。
11+
创建 FILE 数据集。
1212

1313
**用法**
1414

@@ -20,8 +20,8 @@ bl knowledge collection create --name <text> --description <text> [flags]
2020

2121
| 参数 | 类型 | 必填 | 说明 |
2222
| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
23-
| `--name <text>` | string | 是 | 集合名称（1-20 字符） |
24-
| `--description <text>` | string | 是 | 集合描述 |
23+
| `--name <text>` | string | 是 | 数据集名称（1-20 字符） |
24+
| `--description <text>` | string | 是 | 数据集描述 |
2525
| `--store-type <type>` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
2626
| `--oss-region <id>` | string | 否 | OSS region ID（`--store-type custom` 时必填） |
2727
| `--oss-bucket <name>` | string | 否 | OSS bucket 名称（`--store-type custom` 时必填） |
@@ -40,31 +40,31 @@ text 模式：
4040
created: conn-xxx (my-collection, PLATFORM)
4141
```
4242

43-
quiet 模式：输出集合 ID。
43+
quiet 模式：输出数据集 ID。
4444

4545
json 模式：返回 API 原始响应。
4646

4747
**注意事项**
4848

4949
- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
5050
- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
51-
- **无集合删除 API**，创建需谨慎。
51+
- **无数据集删除 API**，创建需谨慎。
5252

5353
**示例**
5454

5555
```bash
56-
# 创建平台托管的集合
56+
# 创建平台托管的数据集
5757
bl knowledge collection create --name my-collection --description "team docs" --workspace-id ws-xxx
5858

59-
# 创建使用自有 OSS bucket 的集合
59+
# 创建使用自有 OSS bucket 的数据集
6060
bl knowledge collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
6161
```
6262

6363
---
6464

6565
#### `bl knowledge collection get`
6666

67-
查看数据集合详情。
67+
查看数据集详情。
6868

6969
**用法**
7070

@@ -74,10 +74,10 @@ bl knowledge collection get (--collection-id <id> | --name <text>) [flags]
7474

7575
**参数**
7676

77-
| 参数 | 类型 | 必填 | 说明 |
78-
| ---------------------- | ------ | ---- | -------- |
79-
| `--collection-id <id>` | string | 否¹ | 集合 ID |
80-
| `--name <text>` | string | 否¹ | 集合名称 |
77+
| 参数 | 类型 | 必填 | 说明 |
78+
| ---------------------- | ------ | ---- | ---------- |
79+
| `--collection-id <id>` | string | 否¹ | 数据集 ID |
80+
| `--name <text>` | string | 否¹ | 数据集名称 |
8181

8282
> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
8383
@@ -95,7 +95,7 @@ name: my-collection
9595
description: team docs
9696
```
9797

98-
quiet 模式：输出集合 ID。
98+
quiet 模式：输出数据集 ID。
9999

100100
json 模式：返回 API 原始响应。
101101

@@ -129,7 +129,7 @@ bl knowledge category list [flags]
129129

130130
| 参数 | 类型 | 必填 | 说明 |
131131
| ---------------------- | ------ | ---- | ------------------------------------------------------ |
132-
| `--collection-id <id>` | string | 否 | 按集合 ID 过滤 |
132+
| `--collection-id <id>` | string | 否 | 按数据集 ID 过滤 |
133133
| `--parent-id <id>` | string | 否 | 列出此分类的子分类 |
134134
| `--name <text>` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
135135
| `--next-token <token>` | string | 否 | 游标分页令牌 |
@@ -182,11 +182,11 @@ bl knowledge category add --name <text> [flags]
182182

183183
**参数**
184184

185-
| 参数 | 类型 | 必填 | 说明 |
186-
| ---------------------- | ------ | ---- | -------------------------------- |
187-
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
188-
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
189-
| `--collection-id <id>` | string | 否 | 创建在此集合下（默认：平台集合） |
185+
| 参数 | 类型 | 必填 | 说明 |
186+
| ---------------------- | ------ | ---- | ------------------------------------ |
187+
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
188+
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
189+
| `--collection-id <id>` | string | 否 | 创建在此数据集下（默认：平台数据集） |
190190

191191
**参数约束**
192192

‎docs/knowledge/knowledge-cli-guide.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
- [检索服务管理](#检索服务管理) → [完整手册](service.md)
1717
- [Chunk 管理](#chunk-管理) → [完整手册](chunk.md)
1818
- [数据中心文件管理](#数据中心文件管理) → [完整手册](file.md)
19-
- [数据中心集合与分类](#数据中心集合与分类) → [完整手册](collection-category.md)
19+
- [数据中心数据集与分类](#数据中心数据集与分类) → [完整手册](collection-category.md)
2020
- [检索与对话](#检索与对话) → [完整手册](search-chat.md)
2121
6. [常见错误与排查](#常见错误与排查)
2222
7. [附录：命令速查表](#附录命令速查表)
@@ -31,7 +31,7 @@
3131
- **文档管理**：上传本地文件、从 OSS 批量导入、查看解析状态、删除、打标签
3232
- **Chunk 级运维**：直接增删改查知识库中的内容切片
3333
- **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
34-
- **数据中心管理**：文件、集合（connector）、分类的增删查
34+
- **数据中心管理**：文件、数据集（collection）、分类的增删查
3535
- **检索与对话**：语义检索（search）、多轮对话（chat）
3636

3737
命令按功能域分为 7 组。所有命令均使用 DashScope API Key 鉴权。
@@ -44,8 +44,8 @@
4444
┌─────────────────────────────────────────────────────────────┐
4545
│ 数据中心 (Data Center) │
4646
│ │
47-
│ 集合 (Collection) ──┬── 分类 (Category) ── 文件 (File) │
48-
│ │ "connector" 可多级嵌套 │
47+
│ 数据集 (Collection) ──┬── 分类 (Category) ── 文件 (File) │
48+
│ │ 可多级嵌套 │
4949
│ └── 默认分类 │
5050
│ │
5151
│ 文件来源：doc upload(本地上传) / doc import-oss(OSS导入) │
@@ -621,13 +621,13 @@ kscli file delete --file-id <id> [flags]
621621

622622
---
623623

624-
### 数据中心集合与分类
624+
### 数据中心数据集与分类
625625

626626
> 📖 [完整手册](collection-category.md) — 5 个命令
627627
628628
#### `kscli collection create`
629629

630-
创建 FILE 数据集合。
630+
创建 FILE 数据集。
631631

632632
```bash
633633
kscli collection create --name <text> --description <text> [flags]
@@ -639,7 +639,7 @@ kscli collection create --name <text> --description <text> [flags]
639639

640640
#### `kscli collection get`
641641

642-
查看数据集合详情。
642+
查看数据集详情。
643643

644644
```bash
645645
kscli collection get (--collection-id <id> | --name <text>) [flags]
@@ -782,13 +782,13 @@ bl config set workspace_id ws-xxx
782782

783783
**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
784784

785-
### 集合无法删除
785+
### 数据集无法删除
786786

787787
**问题**：没有 `collection delete` 命令。
788788

789789
**原因**：暂不支持通过 CLI 删除。
790790

791-
**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
791+
**解决**：创建数据集需谨慎。如需隔离，创建新数据集并迁移文件。
792792

793793
---
794794

@@ -822,8 +822,8 @@ bl config set workspace_id ws-xxx
822822
| `kscli file list` | 文件列表 | `--category-id` |
823823
| `kscli file get` | 文件详情 | `--file-id` |
824824
| `kscli file delete` | 删除文件 | `--file-id`, `--yes` |
825-
| `kscli collection create` | 创建集合 | `--name`, `--description` |
826-
| `kscli collection get` | 集合详情 | `--collection-id`/`--name` |
825+
| `kscli collection create` | 创建数据集 | `--name`, `--description` |
826+
| `kscli collection get` | 数据集详情 | `--collection-id`/`--name` |
827827
| `kscli category list` | 分类列表 | `--collection-id`, `--parent-id` |
828828
| `kscli category add` | 创建分类 | `--name`, `--parent-id` |
829829
| `kscli category delete` | 删除分类 | `--category-id`, `--yes` |
@@ -832,4 +832,4 @@ bl config set workspace_id ws-xxx
832832

833833
## 音视频升级入口
834834

835-
已有文件接入已有库使用 `bl knowledge doc import --index-id <id> --doc-id <fileId>`，kscli 对应 `kscli doc import`。与 `doc upload`（本地上传）和 `doc import-oss`（OSS 注册）分开；历史 fileId 的发现步骤见 [集合与分类](collection-category.md#从-collection-查历史-fileid)。媒体接入参数见 [文档管理](doc.md#已有文件导入与音视频接入)，输出合同见 [检索与问答](search-chat.md)。
835+
已有文件接入已有库使用 `bl knowledge doc import --index-id <id> --doc-id <fileId>`，kscli 对应 `kscli doc import`。与 `doc upload`（本地上传）和 `doc import-oss`（OSS 注册）分开；历史 fileId 的发现步骤见 [数据集与分类](collection-category.md#从-collection-查历史-fileid)。媒体接入参数见 [文档管理](doc.md#已有文件导入与音视频接入)，输出合同见 [检索与问答](search-chat.md)。

‎docs/kscli/collection-category.md‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# 数据中心集合与分类命令手册
1+
# 数据中心数据集与分类命令手册
22

3-
集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
3+
数据集（collection）是数据中心的顶层容器。分类（category）用于组织数据集内的文件，支持多级嵌套。
44

55
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
66
77
---
88

99
#### `kscli collection create`
1010

11-
创建 FILE 数据集合。
11+
创建 FILE 数据集。
1212

1313
**用法**
1414

@@ -20,8 +20,8 @@ kscli collection create --name <text> --description <text> [flags]
2020

2121
| 参数 | 类型 | 必填 | 说明 |
2222
| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
23-
| `--name <text>` | string | 是 | 集合名称（1-20 字符） |
24-
| `--description <text>` | string | 是 | 集合描述 |
23+
| `--name <text>` | string | 是 | 数据集名称（1-20 字符） |
24+
| `--description <text>` | string | 是 | 数据集描述 |
2525
| `--store-type <type>` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
2626
| `--oss-region <id>` | string | 否 | OSS region ID（`--store-type custom` 时必填） |
2727
| `--oss-bucket <name>` | string | 否 | OSS bucket 名称（`--store-type custom` 时必填） |
@@ -40,31 +40,31 @@ text 模式：
4040
created: conn-xxx (my-collection, PLATFORM)
4141
```
4242

43-
quiet 模式：输出集合 ID。
43+
quiet 模式：输出数据集 ID。
4444

4545
json 模式：返回 API 原始响应。
4646

4747
**注意事项**
4848

4949
- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
5050
- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
51-
- **无集合删除 API**，创建需谨慎。
51+
- **无数据集删除 API**，创建需谨慎。
5252

5353
**示例**
5454

5555
```bash
56-
# 创建平台托管的集合
56+
# 创建平台托管的数据集
5757
kscli collection create --name my-collection --description "team docs" --workspace-id ws-xxx
5858

59-
# 创建使用自有 OSS bucket 的集合
59+
# 创建使用自有 OSS bucket 的数据集
6060
kscli collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
6161
```
6262

6363
---
6464

6565
#### `kscli collection get`
6666

67-
查看数据集合详情。
67+
查看数据集详情。
6868

6969
**用法**
7070

@@ -74,10 +74,10 @@ kscli collection get (--collection-id <id> | --name <text>) [flags]
7474

7575
**参数**
7676

77-
| 参数 | 类型 | 必填 | 说明 |
78-
| ---------------------- | ------ | ---- | -------- |
79-
| `--collection-id <id>` | string | 否¹ | 集合 ID |
80-
| `--name <text>` | string | 否¹ | 集合名称 |
77+
| 参数 | 类型 | 必填 | 说明 |
78+
| ---------------------- | ------ | ---- | ---------- |
79+
| `--collection-id <id>` | string | 否¹ | 数据集 ID |
80+
| `--name <text>` | string | 否¹ | 数据集名称 |
8181

8282
> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
8383
@@ -95,7 +95,7 @@ name: my-collection
9595
description: team docs
9696
```
9797

98-
quiet 模式：输出集合 ID。
98+
quiet 模式：输出数据集 ID。
9999

100100
json 模式：返回 API 原始响应。
101101

@@ -129,7 +129,7 @@ kscli category list [flags]
129129

130130
| 参数 | 类型 | 必填 | 说明 |
131131
| ---------------------- | ------ | ---- | ------------------------------------------------------ |
132-
| `--collection-id <id>` | string | 否 | 按集合 ID 过滤 |
132+
| `--collection-id <id>` | string | 否 | 按数据集 ID 过滤 |
133133
| `--parent-id <id>` | string | 否 | 列出此分类的子分类 |
134134
| `--name <text>` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
135135
| `--next-token <token>` | string | 否 | 游标分页令牌 |
@@ -182,11 +182,11 @@ kscli category add --name <text> [flags]
182182

183183
**参数**
184184

185-
| 参数 | 类型 | 必填 | 说明 |
186-
| ---------------------- | ------ | ---- | -------------------------------- |
187-
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
188-
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
189-
| `--collection-id <id>` | string | 否 | 创建在此集合下（默认：平台集合） |
185+
| 参数 | 类型 | 必填 | 说明 |
186+
| ---------------------- | ------ | ---- | ------------------------------------ |
187+
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
188+
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
189+
| `--collection-id <id>` | string | 否 | 创建在此数据集下（默认：平台数据集） |
190190

191191
**参数约束**
192192

0 commit comments

Comments
 (0)