docs(tool-bailian-kb): 完善阿里云百炼知识库管理文档与命令参考

- 更新技能描述，补充命令行工具 kscli 的使用范围与说明
- 细化安装与鉴权步骤，明确不同发行通道及 Node.js 版本要求
- 增加详细的命令用途对照表，便于用户区分不同操作命令
- 优化核心工作流示例，简化上传、建库、部署检索服务步骤
- 补充多种 ID 类型说明，帮助用户正确使用各类标识
- 添加关于危险和不可逆操作的说明及确认要求
- 强调服务版本状态及发布流程，规范草稿与发布版切换
- 新增详细的命令参考文档，覆盖 chunk、config、datacenter、
  doc、kb、query、service 等命令组
- 更新 package 版本号至 0.1.5，标识本次文档与功能更新

Author: clark-fc

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",

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 <kb-id> --file ./docs.pdf                    # 2. 上传本地文档
-kscli doc status --kb-id <kb-id> --doc-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 <fileId> --wait                # 2. 建库并导入 → 得 index-id (pipelineId)
+kscli service create --name my-search --scene search --index-id <index-id>   # 3. 建检索服务 → 得 agent-id（draft）
+kscli service deploy --agent-id <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 <id> --agent-version beta`。
+
+已有文件再入库的简写：`kscli doc upload --file ./a.md --index-id <index-id> --wait`（上传+导入一步完成）。
+
+## 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/&lt;group&gt;.md — 按命令组分文件（kb / doc / service / chunk / datacenter / config / query）
+
+执行不熟悉的命令前，先读对应 reference 或跑 `kscli <命令> --help`。**不要猜 flag。**
+全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`、`--verbose`。
+
+## 危险与不可逆操作
 
-## 命令组速查
+执行以下操作前须向用户确认，脚本化时才用 `--yes` 跳过交互确认：
 
-`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
+- `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`，两个场景要分别查询。

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 <id> (--content <text> | --field <k=v>) [flags]
+```
+
+| Flag | 说明 |
+| --- | --- |
+| `--doc-id <id>` | 归属文档 ID（取自 `doc list`）；**实践中所有库类型都必填** |
+| `--content <text>` | Chunk 正文，≤6000 字符（文档型库）；与 `--content-file` 二选一 |
+| `--content-file <path>` | 从 UTF-8 纯文本文件读正文（.md/.txt 等） |
+| `--title <text>` | Chunk 标题，≤50 字符 |
+| `--image-url <url>` | Chunk 图片 URL（可重复，≤10 个） |
+| `--field <key=value>` | 表格/图片型库的任意字段（可重复，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 <id> [flags]
+```
+
+| Flag | 说明 |
+| --- | --- |
+| `--doc-id <id>` | 只看该文档的 chunk |
+| `--page-number <n>` / `--page-size <n>` | 分页（服务端默认 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 <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+| Flag | 说明 |
+| --- | --- |
+| `--chunk-id <id>` | Chunk ID（`chunk list` 的 `metadata._id`） |
+| `--doc-id <id>` | 归属文档 ID（`chunk list` 的 `metadata.doc_id`） |
+| `--content <text>` | 新内容，10-6000 字符；与 `--content-file` 二选一 |
+| `--content-file <path>` | 从 UTF-8 纯文本文件读新内容 |
+| `--title <text>` | 标题，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 <id> --chunk-id <id> [flags]
+```
+
+| Flag | 说明 |
+| --- | --- |
+| `--chunk-id <id>` | 要删的 chunk ID（可重复；超过 10 个自动分批发送） |
+| `--yes` | 跳过交互确认 |
+
+```bash
+kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes
+```

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 <key> --value <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 <version>]
+```
+
+| Flag | 说明 |
+| --- | --- |
+| `--to <version>` | 安装该精确版本而非最新版 |
+
+Notes：
+
+- 管理命令在 `knowledge` 发行通道；若 `kscli update` 后管理命令消失（升到了 latest），用
+  `npm install -g knowledge-studio-cli@knowledge` 装回。
+
+```bash
+kscli update
+kscli update --to 0.1.14
+```