diff --git a/CHANGELOG.md b/CHANGELOG.md
index eda6e079..4adfbe1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,29 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 [中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
 
+## [1.16.0] - 2026-08-17
+
+> Full knowledge-base lifecycle management arrives in the CLI: create and configure knowledge bases, upload documents, tune chunks, and deploy retrieval/Q&A services — all from `bl knowledge` and `kscli`.
+
+### Added
+
+- **Knowledge base management** — `bl knowledge create` / `list` / `info` / `update` / `delete` manage knowledge bases end to end; `bl knowledge stats` reports document counts and usage over a past time range.
+- **Document management** — `bl knowledge doc upload` uploads local files or whole directories (recursive scan, skips unsupported formats and tool directories like `node_modules`); `doc list` / `status` / `tag` / `delete` cover the rest of the document lifecycle, and `doc import-oss` imports documents from OSS.
+- **Retrieval / Q&A service management** — `bl knowledge service list` / `get` / `create` / `update` / `deploy` / `delete` / `copy` manage retrieval and Q&A service configurations, including deploying a draft to a published version.
+- **Chunk management** — `bl knowledge chunk add` / `list` / `update` / `delete` inspect and fine-tune document chunks.
+- **Data-center management** — `bl knowledge category list` / `add` / `delete`, `bl knowledge file list` / `get` / `delete`, and `bl knowledge collection create` / `get` manage categories, raw files, and data collections.
+- **Service version selection for retrieval and chat** — `bl knowledge search` and `bl knowledge chat` accept `--agent-version` to call the beta (draft) config for debugging or a specific published version.
+- **`kscli` parity** — all new knowledge commands are also available in Knowledge Studio CLI under shorter paths, e.g. `kscli kb list`, `kscli doc upload`, `kscli service deploy`.
+
+### Removed
+
+- **`bl knowledge search --query-history` removed** — the parameter never took effect; use `bl knowledge chat` with `--message` history for multi-turn scenarios.
+
+### Internal
+
+- Requests now carry a static OpenAPI source identification header for backend channel attribution.
+- Added knowledge-base E2E suites, including five user-journey scenarios covering cold start, content ops, chunk tuning, service tuning, and the data plane.
+
 ## [1.15.1] - 2026-08-17
 
 ### Added
diff --git a/CHANGELOG.zh.md b/CHANGELOG.zh.md
index 114549a1..962c6771 100644
--- a/CHANGELOG.zh.md
+++ b/CHANGELOG.zh.md
@@ -6,6 +6,29 @@
 
 [English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
 
+## [1.16.0] - 2026-08-17
+
+> CLI 迎来知识库全生命周期管理：从创建配置知识库、上传文档、调优切片，到部署检索/问答服务，均可通过 `bl knowledge` 与 `kscli` 完成。
+
+### 新增
+
+- **知识库管理** —— `bl knowledge create` / `list` / `info` / `update` / `delete` 覆盖知识库的完整生命周期；`bl knowledge stats` 查询指定过去时间段内的文档数量与用量统计。
+- **文档管理** —— `bl knowledge doc upload` 支持上传本地文件或整个目录（递归扫描，自动跳过不支持的格式及 `node_modules` 等工具目录）；`doc list` / `status` / `tag` / `delete` 覆盖文档生命周期其余环节，`doc import-oss` 支持从 OSS 导入文档。
+- **检索 / 问答服务管理** —— `bl knowledge service list` / `get` / `create` / `update` / `deploy` / `delete` / `copy` 管理检索与问答服务配置，支持将草稿部署为正式版本。
+- **切片管理** —— `bl knowledge chunk add` / `list` / `update` / `delete` 查看并精调文档切片。
+- **数据中心管理** —— `bl knowledge category list` / `add` / `delete`、`bl knowledge file list` / `get` / `delete`、`bl knowledge collection create` / `get` 管理类目、原始文件与数据集。
+- **检索与问答支持指定服务版本** —— `bl knowledge search` 和 `bl knowledge chat` 新增 `--agent-version`，可调用 beta（草稿）配置进行调试，或指定已发布的版本号。
+- **`kscli` 同步支持** —— 全部新知识库命令在 Knowledge Studio CLI 中以更短路径提供，如 `kscli kb list`、`kscli doc upload`、`kscli service deploy`。
+
+### 移除
+
+- **移除 `bl knowledge search --query-history`** —— 该参数此前并未实际生效；多轮场景请改用 `bl knowledge chat` 并通过 `--message` 传入对话历史。
+
+### 内部
+
+- 请求现在携带静态的 OpenAPI 来源标识请求头，用于后端渠道归因。
+- 新增知识库 E2E 测试套件，含冷启动、内容运营、切片调优、服务调优、数据面五条用户旅程场景。
+
 ## [1.15.1] - 2026-08-17
 
 ### 新增
diff --git a/docs/agents/cli-e2e-tests.md b/docs/agents/cli-e2e-tests.md
index 08d3880e..cfae0770 100644
--- a/docs/agents/cli-e2e-tests.md
+++ b/docs/agents/cli-e2e-tests.md
@@ -6,6 +6,7 @@
 | --------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | **共享基建**    | `packages/e2e`                                        | gating、子进程 runner、output、globalSetup（`private`，不发布）                          |
 | **命令 E2E**    | `packages/commands/tests/e2e`                         | help、缺参、dry-run、live（gated）；每用例最小路由                                       |
+| **Journey E2E** | `packages/commands/tests/e2e/knowledge/journeys`      | 用户旅程全链路（跨命令回路 + 标记词召回闭环），全部 live gated；见 `journeys/README.md`  |
 | **bl smoke**    | `packages/cli/tests/e2e/registry.smoke.e2e.test.ts`   | 产品 map 全部 path `--help`、分组 help、根 help                                          |
 | **kscli smoke** | `packages/kscli/tests/e2e/registry.smoke.e2e.test.ts` | 从 `kscli/src/commands.ts` 推导 path/分组；identity（`--version`、`search --help` path） |
 | **runtime**     | `packages/runtime/tests`                              | `proxy.e2e`、console 跨域 flag 拒绝                                                      |
@@ -27,7 +28,7 @@
 
 ### commands E2E
 
-- 路径：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`
+- 路径：`packages/commands/tests/e2e/<kebab-topic>.e2e.test.ts`；knowledge 领域集中在 `packages/commands/tests/e2e/knowledge/` 子目录（新增 knowledge 命令测试放这里）
 - 子进程：`runCommandE2e(routes, args)` from `./helpers.ts`（spawn `harness/main.ts`，`routes` 为本 topic 最小 path → export 映射）
 - fixtures：`packages/commands/tests/e2e/fixtures/`
 - 路由常量：`topic-routes.ts`（按 topic 维护，**非**全量产品 map）
@@ -78,6 +79,14 @@ describe.skipIf(<ready>)("e2e: <topic>（DashScope …）", () => {
 3. **--dry-run**：实现在联网/上传/写盘**之前**返回；断言 stdout JSON/文本
 4. **真实集成**：放在 skip 块**末尾**
 
+## Journey 层（用户旅程全链路）
+
+- **定位**：命令 E2E 验单命令契约；journey 验“用户带着目标跨命令走通回路”，结构性断言不在 journey 重复
+- **闭环断言**：fixture 埋独特标记词，以“标记词能否被召回”判定回路闭合；硬断言 fail，软断言 `recordSoft` 落报告人工复核
+- **日志产物**：`createJourneyReporter` 在 `test/output/<session>/` 落盘 `journey-report.md`、分步 stdout/stderr、`resources.json`（未清理资源警示）
+- **入口**：`pnpm run test:journey`；旅程清单与约定见 [journeys/README.md](../../packages/commands/tests/e2e/knowledge/journeys/README.md)
+- **新增命令时**：评估是否属于某条旅程的环节，是则纳入对应 journey 并更新 README 映射表
+
 ## 增删命令同步
 
 - **commands export** + **topic 路由**（`topic-routes.ts` 或测试文件内 `ROUTES`）+ **产品 map**（`cli/commands.ts` / `kscli/commands.ts`）
diff --git a/docs/knowledge/chunk.md b/docs/knowledge/chunk.md
new file mode 100644
index 00000000..378ee808
--- /dev/null
+++ b/docs/knowledge/chunk.md
@@ -0,0 +1,248 @@
+# Chunk 管理命令手册
+
+Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge chunk add`
+
+直接向知识库添加 chunk。
+
+**用法**
+
+```bash
+bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                                                        |
+| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                                                                   |
+| `--doc-id <id>`         | string | 否²  | 所属文档 ID；表格/图片知识库必填，文档型可选                                                |
+| `--content <text>`      | string | 否¹  | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥                              |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥                           |
+| `--title <text>`        | string | 否   | Chunk 标题，最多 50 字符（文档型）                                                          |
+| `--image-url <url>`     | array  | 否   | Chunk 图片 URL（可重复，最多 10 个；文档型）                                                |
+| `--field <key=value>`   | array  | 否¹  | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |
+
+> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
+> ² 表格/图片知识库必须提供 `--doc-id`。文档型知识库可选。
+
+**参数约束**
+
+- `--field` 与 `--content`/`--content-file`/`--title`/`--image-url` 互斥
+- `--content` 与 `--content-file` 互斥
+- `--content` 最多 6000 字符
+- `--title` 最多 50 字符
+- `--image-url` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+chunk created (pipeline: idx-xxx)
+List chunks to find the new chunk id.
+```
+
+quiet 模式：无输出（成功退出码 0）。
+
+json 模式：返回 API 原始响应（不含 chunk ID）。
+
+**注意事项**
+
+- 支持文档/表格/图片知识库；音视频知识库不支持。
+- API 响应不含 chunk ID，需用 `chunk list` 查找新 chunk。
+- API 幂等但限流 10 次/秒，批量脚本需自行节流。
+- 表格/图片知识库用 `--field`，键为 Excel 列名，值为字符串。
+
+**示例**
+
+```bash
+# 添加文本 chunk
+bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
+
+# 添加表格行（字段方式）
+bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
+
+# 从文件读取内容
+bl knowledge chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx
+```
+
+---
+
+#### `bl knowledge chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+**用法**
+
+```bash
+bl knowledge chunk list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--doc-id <id>`     | string | 否   | 只显示属于此文档的 chunk       |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
+  chunk content preview (truncated at 200 chars)…
+total: 1
+```
+
+> 如果 chunk 被排除检索，行尾会显示 `[excluded from retrieval]`。
+
+quiet 模式：每行一个 `metadata._id`（chunk ID），用于管道传给 update/delete。
+
+json 模式：返回 API 原始响应，`data.nodes[]` 含完整 chunk 数据。
+
+**注意事项**
+
+- 用 `metadata._id` 作为 chunk ID，`metadata.doc_id` 作为文档 ID，在 chunk update/delete 中使用。
+- 页大小默认 20，最大 100。
+
+**示例**
+
+```bash
+# 列出所有 chunk
+bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
+
+# 只看某文档的 chunk
+bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
+```
+
+---
+
+#### `bl knowledge chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+**用法**
+
+```bash
+bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明                                                   |
+| ----------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--index-id <id>`       | string | 是   | 知识库 ID                                              |
+| `--chunk-id <id>`       | string | 是   | Chunk ID（`metadata._id`，来自 chunk list 输出）       |
+| `--doc-id <id>`         | string | 是   | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） |
+| `--content <text>`      | string | 否¹  | 新内容，10-6000 字符；与 `--content-file` 互斥         |
+| `--content-file <path>` | string | 否¹  | 从 UTF-8 文本文件读取新内容                            |
+| `--title <text>`        | string | 否   | Chunk 标题，0-50 字符（空字符串清除标题；不传则不变）  |
+| `--exclude`             | switch | 否²  | 将此 chunk 排除出检索                                  |
+| `--include`             | switch | 否²  | 将此 chunk 恢复检索（默认行为）                        |
+
+> ¹ `--content` 与 `--content-file` 互斥。
+> ² `--exclude` 与 `--include` 互斥。
+
+**参数约束**
+
+- `--content` 与 `--content-file` 互斥
+- `--exclude` 与 `--include` 互斥
+- 至少提供一个更新项（`--content`/`--content-file`/`--title`/`--exclude`/`--include`）
+- `--content` 长度 10-6000 字符
+- `--title` 最多 50 字符
+
+**输出**
+
+text 模式：
+
+```
+updated: chunk-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 内容必须 10-6000 字符，且不超过知识库的 max chunk size。
+- `--content-file` 期望 UTF-8 纯文本文件，不解析 `.docx`/`.pdf` 等文档格式。
+- 仅切换 `--exclude`/`--include` 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。
+
+**示例**
+
+```bash
+# 修改内容
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx
+
+# 排除 chunk 不参与检索
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
+
+# 恢复检索
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include
+```
+
+---
+
+#### `bl knowledge chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+**用法**
+
+```bash
+bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                             |
+| ----------------- | ------ | ---- | ------------------------------------------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID                                        |
+| `--chunk-id <id>` | array  | 是   | Chunk ID（可重复，每批最多 10 个，超出自动分批） |
+| `--yes`           | switch | 否   | 跳过确认提示                                     |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 chunk(s) in 1 batch(es)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 `{ deleted_count, batches }`。
+
+**注意事项**
+
+- 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。
+- 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。
+- Chunk 被永久移除，不可恢复。
+
+**示例**
+
+```bash
+# 删除多个 chunk
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/collection-category.md b/docs/knowledge/collection-category.md
new file mode 100644
index 00000000..92a24aa6
--- /dev/null
+++ b/docs/knowledge/collection-category.md
@@ -0,0 +1,268 @@
+# 数据中心集合与分类命令手册
+
+集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge collection create`
+
+创建 FILE 数据集合。
+
+**用法**
+
+```bash
+bl knowledge collection create --name <text> --description <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                             |
+| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--name <text>`        | string | 是   | 集合名称（1-20 字符）                                            |
+| `--description <text>` | string | 是   | 集合描述                                                         |
+| `--store-type <type>`  | string | 否   | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
+| `--oss-region <id>`    | string | 否   | OSS region ID（`--store-type custom` 时必填）                    |
+| `--oss-bucket <name>`  | string | 否   | OSS bucket 名称（`--store-type custom` 时必填）                  |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--store-type` 只能是 `platform` 或 `custom`
+- `--store-type custom` 时 `--oss-region` 和 `--oss-bucket` 必填
+
+**输出**
+
+text 模式：
+
+```
+created: conn-xxx  (my-collection, PLATFORM)
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
+- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
+- **无集合删除 API**，创建需谨慎。
+
+**示例**
+
+```bash
+# 创建平台托管的集合
+bl knowledge collection create --name my-collection --description "team docs" --workspace-id ws-xxx
+
+# 创建使用自有 OSS bucket 的集合
+bl knowledge collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
+```
+
+---
+
+#### `bl knowledge collection get`
+
+查看数据集合详情。
+
+**用法**
+
+```bash
+bl knowledge collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明     |
+| ---------------------- | ------ | ---- | -------- |
+| `--collection-id <id>` | string | 否¹  | 集合 ID  |
+| `--name <text>`        | string | 否¹  | 集合名称 |
+
+> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--collection-id` 和 `--name` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+id: conn-xxx
+name: my-collection
+description: team docs
+```
+
+quiet 模式：输出集合 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。
+
+**示例**
+
+```bash
+# 按 ID 查询
+bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx
+
+# 按名称查询
+bl knowledge collection get --name my-collection
+```
+
+---
+
+#### `bl knowledge category list`
+
+列出数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category list [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                                   |
+| ---------------------- | ------ | ---- | ------------------------------------------------------ |
+| `--collection-id <id>` | string | 否   | 按集合 ID 过滤                                         |
+| `--parent-id <id>`     | string | 否   | 列出此分类的子分类                                     |
+| `--name <text>`        | string | 否   | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
+| `--next-token <token>` | string | 否   | 游标分页令牌                                           |
+| `--max-result <n>`     | number | 否   | 每页条数（默认：20）                                   |
+
+**输出**
+
+text 模式：
+
+```
+cate-xxx  product-docs
+cate-yyy  system-docs  [default]
+next: --next-token eyJ...
+```
+
+> 标记 `[default]` 的是文件未指定分类时的默认归属。
+
+quiet 模式：每行一个 `categoryId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出所有分类
+bl knowledge category list --workspace-id ws-xxx
+
+# 按名称过滤
+bl knowledge category list --name my-category
+
+# 翻页
+bl knowledge category list --next-token eyJ...
+```
+
+---
+
+#### `bl knowledge category add`
+
+创建数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category add --name <text> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                             |
+| ---------------------- | ------ | ---- | -------------------------------- |
+| `--name <text>`        | string | 是   | 分类名称（1-20 字符）            |
+| `--parent-id <id>`     | string | 否   | 创建为指定分类的子分类           |
+| `--collection-id <id>` | string | 否   | 创建在此集合下（默认：平台集合） |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+
+**输出**
+
+text 模式：
+
+```
+created: cate-xxx  (product-docs)
+```
+
+quiet 模式：输出分类 ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 用分类按业务域组织数据中心文件。
+
+**示例**
+
+```bash
+# 创建分类
+bl knowledge category add --name product-docs --workspace-id ws-xxx
+
+# 创建子分类
+bl knowledge category add --name sub --parent-id cate-xxx
+```
+
+---
+
+#### `bl knowledge category delete`
+
+删除数据中心分类。
+
+**用法**
+
+```bash
+bl knowledge category delete --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明         |
+| -------------------- | ------ | ---- | ------------ |
+| `--category-id <id>` | string | 是   | 分类 ID      |
+| `--yes`              | switch | 否   | 跳过确认提示 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: cate-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。
+
+**示例**
+
+```bash
+# 删除分类（交互确认）
+bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge category delete --category-id cate-xxx --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/doc.md b/docs/knowledge/doc.md
new file mode 100644
index 00000000..5689d484
--- /dev/null
+++ b/docs/knowledge/doc.md
@@ -0,0 +1,344 @@
+# 文档管理命令手册
+
+文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+**用法**
+
+```bash
+bl knowledge doc list --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                           |
+| ------------------- | ------ | ---- | ------------------------------ |
+| `--index-id <id>`   | string | 是   | 知识库 ID                      |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：10，最大 100） |
+
+**参数约束**
+
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个文档，`FAILED` 状态的文档红色高亮。
+
+```
+doc-xxx  COMPLETED  intro.md  md  1024
+total: 1
+```
+
+quiet 模式：每行一个 `doc_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `doc_id` 与 `file_id` 的关系：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `knowledge doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。
+- 页大小默认 10（服务端默认），最大 100。
+
+**示例**
+
+```bash
+# 列出文档
+bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
+
+# 每页 100 条
+bl knowledge doc list --index-id idx-xxx --page-size 100
+```
+
+---
+
+#### `bl knowledge doc status`
+
+查看知识库导入任务状态。
+
+**用法**
+
+```bash
+bl knowledge doc status --index-id <id> --job-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                |
+| --------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`           | string | 是   | 知识库 ID                                           |
+| `--job-id <id>`             | string | 是   | 导入任务 ID（`ingestionId`，由 create/upload 返回） |
+| `--page-number <n>`         | number | 否   | 页码                                                |
+| `--page-size <n>`           | number | 否   | 每页条数                                            |
+| `--wait`                    | switch | 否   | 轮询直到任务到达终态                                |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                             |
+
+**输出**
+
+text 模式：
+
+```
+status: COMPLETED
+  doc-xxx  COMPLETED  intro.md
+```
+
+quiet 模式：输出任务状态（`PENDING`/`RUNNING`/`COMPLETED`）。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含每个文档的状态。
+
+**注意事项**
+
+- `--index-id` 和 `--job-id` 服务端均要求必传，只传一个会返回 `SystemError`。
+- 整体任务状态为 `PENDING` / `RUNNING` / `COMPLETED`（无 `FAILED` 值）。
+- 单个文档可能解析失败（如 `PARSE_FAILED`），此时 CLI 以非零退出码报错，服务端消息原样透传。
+- 如果服务端对空闲知识库返回 `SystemError`，说明该 job 可能不存在。
+
+**示例**
+
+```bash
+# 查看任务状态
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+
+# 轮询等待完成，10 秒间隔
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
+```
+
+---
+
+#### `bl knowledge doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+**用法**
+
+```bash
+bl knowledge doc upload --file <path> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                             |
+| --------------------------- | ------ | ---- | ---------------------------------------------------------------- |
+| `--file <path>`             | array  | 是   | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
+| `--index-id <id>`           | string | 否   | 上传后导入到此知识库（所有文件合并为一个导入任务）               |
+| `--category-id <id>`        | string | 否   | 目标数据中心分类（默认：工作区默认分类）                         |
+| `--tag <text>`              | array  | 否   | 文件标签（可重复），应用到每个上传的文件                         |
+| `--wait`                    | switch | 否   | 轮询导入任务直到终态（需要 `--index-id`）                        |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                          |
+
+**参数约束**
+
+- `--wait` 要求同时指定 `--index-id`
+
+**输出**
+
+text 模式：
+
+```
+intro.md  file-xxx  registered
+job: job-xxx
+status: COMPLETED
+
+Uploaded 1 file.
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回自定义结构，包含 `files`（路径和 fileId）、`skipped`、`index_id`、`ingestion_id`、`final_status`。
+
+**注意事项**
+
+- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。
+- 目录递归扫描，`node_modules`、`.git` 等自动跳过。
+- 多文件按顺序处理（无并发），避免 OSS 限流。
+- 支持的文件格式：`.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif`
+- 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。
+
+**示例**
+
+```bash
+# 上传单个文件
+bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
+
+# 上传多个文件并导入到知识库，等待完成
+bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
+
+# 上传整个目录
+bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
+
+# 干跑预览（查看将上传和跳过的文件）
+bl knowledge doc upload --file ./docs/ --dry-run --verbose
+```
+
+---
+
+#### `bl knowledge doc delete`
+
+从知识库中删除文档及其 chunk。
+
+**用法**
+
+```bash
+bl knowledge doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明              |
+| ----------------- | ------ | ---- | ----------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID         |
+| `--doc-id <id>`   | array  | 是   | 文档 ID（可重复） |
+| `--yes`           | switch | 否   | 跳过确认提示      |
+
+**输出**
+
+text 模式：
+
+```
+deleted: 2 document(s)
+  doc-a
+  doc-b
+```
+
+quiet 模式：每行一个已删除的 `doc_id`。
+
+json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 列表。
+
+**注意事项**
+
+- 只从知识库索引中移除文档，数据中心源文件不受影响（用 `file delete` 删除源文件）。
+- `doc_id` 应从 `knowledge doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。
+- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。
+- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
+
+**示例**
+
+```bash
+# 删除单个文档
+bl knowledge doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
+
+# 批量删除，跳过确认
+bl knowledge doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
+```
+
+---
+
+#### `bl knowledge doc tag`
+
+批量更新数据中心文件的标签。
+
+**用法**
+
+```bash
+bl knowledge doc tag --doc-id <id> --tag <text> [flags]
+```
+
+**参数**
+
+| 参数            | 类型   | 必填 | 说明                                                   |
+| --------------- | ------ | ---- | ------------------------------------------------------ |
+| `--doc-id <id>` | array  | 是   | 数据中心文件 ID（可重复，最多 20 个/次）               |
+| `--tag <text>`  | array  | 是   | 标签（可重复），应用到每个 `--doc-id`                  |
+| `--mode <mode>` | string | 否   | 更新模式：`append`（默认，追加）或 `overwrite`（覆盖） |
+
+**参数约束**
+
+- `--doc-id` 最多 20 个/次
+- `--tag` 最多 100 个
+- 每个标签最多 32 字符
+- 标签总长度最多 700 字符
+- `--mode` 只能是 `append` 或 `overwrite`
+
+**输出**
+
+text 模式：
+
+```
+tagged: 2 file(s) with [project-a, draft]
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 同一组标签应用到所有 `--doc-id`；不同标签集需多次执行。
+
+**示例**
+
+```bash
+# 追加标签
+bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
+
+# 覆盖标签
+bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
+```
+
+---
+
+#### `bl knowledge doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+**用法**
+
+```bash
+bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+**参数**
+
+| 参数                 | 类型   | 必填 | 说明                                  |
+| -------------------- | ------ | ---- | ------------------------------------- |
+| `--bucket <name>`    | string | 是   | 已授权的 OSS bucket 名称              |
+| `--region <id>`      | string | 是   | OSS region ID（如 `cn-beijing`）      |
+| `--oss-key <key>`    | array  | 是   | OSS 对象 key（可重复，最多 10 个/次） |
+| `--category-id <id>` | string | 否   | 目标数据中心分类（默认：默认分类）    |
+| `--tag <text>`       | array  | 否   | 文件标签（可重复，最多 10 个）        |
+| `--overwrite`        | switch | 否   | 覆盖之前从相同 OSS key 导入的文件     |
+
+**参数约束**
+
+- `--oss-key` 最多 10 个/次
+- `--tag` 最多 10 个
+
+**输出**
+
+text 模式：
+
+```
+imported: 2 file(s)
+  file-a  SUCCESS  docs/a.pdf
+  file-b  SUCCESS  docs/b.docx
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应，`data.addFileResultList[]` 包含每个文件的 fileId、status 和 ossKey。
+
+**注意事项**
+
+- bucket 必须事先授权给平台服务角色（RAM 中的 `AliyunServiceRoleForBailian`）。
+- 文件名取自 OSS key 的 basename。
+- `--overwrite` 会替换之前导入的文件并生成**新的 fileId**（旧 fileId 失效）。
+
+**示例**
+
+```bash
+# 导入单个文件
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
+
+# 导入多个文件并覆盖
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/file.md b/docs/knowledge/file.md
new file mode 100644
index 00000000..4f88a198
--- /dev/null
+++ b/docs/knowledge/file.md
@@ -0,0 +1,157 @@
+# 数据中心文件管理命令手册
+
+数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge file list`
+
+列出数据中心分类下的文件。
+
+**用法**
+
+```bash
+bl knowledge file list --category-id <id> [flags]
+```
+
+**参数**
+
+| 参数                   | 类型   | 必填 | 说明                                               |
+| ---------------------- | ------ | ---- | -------------------------------------------------- |
+| `--category-id <id>`   | string | 是   | 分类 ID（通过 `category list` 或 `file get` 获取） |
+| `--name <text>`        | string | 否   | 按文件名过滤                                       |
+| `--file-id <id>`       | array  | 否   | 按文件 ID 过滤（可重复）                           |
+| `--next-token <token>` | string | 否   | 游标分页令牌（从上次输出获取）                     |
+| `--max-result <n>`     | number | 否   | 每页条数                                           |
+
+**输出**
+
+text 模式：
+
+```
+file-xxx  SUCCESS  intro.md  1024
+next: --next-token eyJ...
+```
+
+quiet 模式：每行一个 `fileId`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- `--category-id` 必须是真实的分类 ID。与上传 API 不同，字面量 `default` 在此不被解析，传入会返回空列表。通过 `file get` 的 category 字段或 `category list` 获取真实 ID。
+- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
+
+**示例**
+
+```bash
+# 列出分类下文件
+bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx
+
+# 按名称过滤
+bl knowledge file list --category-id cate-xxx --name report
+
+# 翻页
+bl knowledge file list --category-id cate-xxx --next-token eyJ...
+```
+
+---
+
+#### `bl knowledge file get`
+
+查看数据中心文件详情。
+
+**用法**
+
+```bash
+bl knowledge file get --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明            |
+| ---------------- | ------ | ---- | --------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID |
+
+**输出**
+
+text 模式：
+
+```
+id: file-xxx
+name: intro.md
+type: md
+size: 1024
+status: SUCCESS
+parser: AUTO_SELECT
+category: cate-xxx
+uploaded: 2026-01-01T00:00:00Z
+tags: project-a, draft
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 无特殊注意事项。
+
+**示例**
+
+```bash
+# 查看文件详情
+bl knowledge file get --file-id file-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge file delete`
+
+从数据中心永久删除文件。
+
+**用法**
+
+```bash
+bl knowledge file delete --file-id <id> [flags]
+```
+
+**参数**
+
+| 参数             | 类型   | 必填 | 说明            |
+| ---------------- | ------ | ---- | --------------- |
+| `--file-id <id>` | string | 是   | 数据中心文件 ID |
+| `--yes`          | switch | 否   | 跳过确认提示    |
+
+**输出**
+
+text 模式：
+
+```
+deleted: file-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。
+- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。
+
+**示例**
+
+```bash
+# 删除文件（交互确认）
+bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge file delete --file-id file-xxx --yes
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/kb.md b/docs/knowledge/kb.md
new file mode 100644
index 00000000..25fcf5e1
--- /dev/null
+++ b/docs/knowledge/kb.md
@@ -0,0 +1,340 @@
+# 知识库管理命令手册
+
+知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge list`
+
+列出工作区中的知识库。
+
+**用法**
+
+```bash
+bl knowledge list [flags]
+```
+
+**参数**
+
+| 参数                | 类型   | 必填 | 说明                              |
+| ------------------- | ------ | ---- | --------------------------------- |
+| `--name <text>`     | string | 否   | 按知识库名称模糊过滤（1-20 字符） |
+| `--page-number <n>` | number | 否   | 页码（默认：1）                   |
+| `--page-size <n>`   | number | 否   | 每页条数（默认：20，最大 100）    |
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。
+
+```
+idx-xxx  my-kb  text-embedding-v4  600  product docs
+total: 1
+```
+
+quiet 模式：每行一个知识库 ID。
+
+json 模式：返回 API 原始响应，`data.rows[]` 包含完整知识库信息。
+
+**注意事项**
+
+- 返回的 `id` 字段作为后续命令的 `--index-id` 使用。
+
+**示例**
+
+```bash
+# 列出所有知识库
+bl knowledge list --workspace-id ws-xxx
+
+# 按名称过滤，第二页
+bl knowledge list --name demo --page-number 2 --page-size 50
+```
+
+---
+
+#### `bl knowledge info`
+
+查看知识库配置详情。
+
+**用法**
+
+```bash
+bl knowledge info --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明      |
+| ----------------- | ------ | ---- | --------- |
+| `--index-id <id>` | string | 是   | 知识库 ID |
+
+**输出**
+
+text 模式：按诊断维度分组展示。
+
+```
+Basic:
+  id: idx-xxx
+  name: my-kb
+  description: product docs
+  dataType: ...
+Indexing:   [immutable — recreate required to change]
+  embeddingModelName: text-embedding-v4
+  embeddingDimension: 1024
+  chunkSize: 600
+  overlapSize: ...
+  chunkMode: ...
+  separator: ...
+Retrieval:
+  rerankModelName: ...
+  rerankMinScore: ...
+  rerankTopN: ...
+  rerankMode: ...
+  enableRewrite: ...
+  denseSimilarityTopK: ...
+  sparseSimilarityTopK: ...
+Data:
+  sourceType: ...
+  connectorId: ...
+```
+
+quiet 模式：输出知识库 ID。
+
+json 模式：返回知识库完整配置 JSON。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 查看知识库详情
+bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge create`
+
+创建知识库并导入数据中心文件或分类。
+
+**用法**
+
+```bash
+bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                     |
+| --------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--name <text>`             | string | 是   | 知识库名称（1-20 字符，工作区内唯一）                    |
+| `--doc-id <id>`             | array  | 否¹  | 数据中心文件 ID（可重复）；与 `--category-id` 互斥       |
+| `--category-id <id>`        | array  | 否¹  | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
+| `--embedding-model <name>`  | string | 否   | 向量模型名称（默认：`text-embedding-v4`）                |
+| `--chunk-size <n>`          | number | 否   | 切片大小，字符数（默认：600，建议 300-800）              |
+| `--wait`                    | switch | 否   | 轮询初始导入任务直到终态                                 |
+| `--poll-interval <seconds>` | number | 否   | 轮询间隔秒数（默认：5）                                  |
+
+> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。
+
+**参数约束**
+
+- `--name` 长度 1-20 字符
+- `--doc-id` 和 `--category-id` 互斥，必须提供其一
+
+**输出**
+
+text 模式：
+
+```
+index_id: idx-xxx
+ingestion_id: job-xxx
+status: COMPLETED
+Next: check the import job status, then search against this knowledge base.
+```
+
+quiet 模式：只输出知识库 ID。
+
+json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 `ingestionId`（导入任务 ID）。`--wait` 时追加 `final_status` 字段。
+
+**注意事项**
+
+- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
+- 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
+- 使用 `doc status` 或 `--wait` 跟踪导入进度。
+- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
+
+**示例**
+
+```bash
+# 从指定文件创建知识库
+bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx
+
+# 从分类导入并等待导入完成
+bl knowledge create --name demo --category-id cate-xxx --wait
+
+# 指定向量模型和切片大小
+bl knowledge create --name my-kb --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+**用法**
+
+```bash
+bl knowledge update --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数                         | 类型   | 必填 | 说明                                                     |
+| ---------------------------- | ------ | ---- | -------------------------------------------------------- |
+| `--index-id <id>`            | string | 是   | 知识库 ID                                                |
+| `--name <text>`              | string | 否   | 新名称（1-20 字符）                                      |
+| `--description <text>`       | string | 否   | 新描述                                                   |
+| `--rerank-min-score <score>` | number | 否   | rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤） |
+
+**参数约束**
+
+- 至少提供 `--name`、`--description`、`--rerank-min-score` 之一，否则报错 "Nothing to update"
+- `--name` 长度 1-20 字符
+- `--rerank-min-score` 范围 0-1
+
+**输出**
+
+text 模式：
+
+```
+updated: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
+
+**示例**
+
+```bash
+# 更新描述
+bl knowledge update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx
+
+# 调整 rerank 阈值
+bl knowledge update --index-id idx-xxx --rerank-min-score 0.3
+```
+
+---
+
+#### `bl knowledge delete`
+
+删除知识库及其所有文档和 chunk。
+
+**用法**
+
+```bash
+bl knowledge delete --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明         |
+| ----------------- | ------ | ---- | ------------ |
+| `--index-id <id>` | string | 是   | 知识库 ID    |
+| `--yes`           | switch | 否   | 跳过确认提示 |
+
+**输出**
+
+text 模式：
+
+```
+deleted: idx-xxx
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **不可逆操作**：知识库及所有索引内容被永久删除。
+- 数据中心中的源文件不受影响，仅删除知识库索引。
+- 不带 `--yes` 时，CLI 会先查询知识库名称和文档数量作为确认摘要。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge delete --index-id idx-xxx --yes
+```
+
+---
+
+#### `bl knowledge stats`
+
+查看知识库存储和 QPS 监控数据。
+
+**用法**
+
+```bash
+bl knowledge stats --index-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明                                            |
+| ----------------- | ------ | ---- | ----------------------------------------------- |
+| `--index-id <id>` | string | 是   | 知识库 ID                                       |
+| `--start <time>`  | string | 否   | 范围起始：Unix 秒或 ISO 日期（默认：24 小时前） |
+| `--end <time>`    | string | 否   | 范围结束：Unix 秒或 ISO 日期（默认：当前时间）  |
+
+**输出**
+
+text 模式：
+
+```
+plan: ...
+storage: 100 / 1000
+peak qps: 5
+qps windows: 24 data point(s)
+```
+
+quiet 模式：输出 json 格式。
+
+json 模式：返回 API 原始响应，包含 `storageMonitorData` 和 `qpsMonitorData`。
+
+**注意事项**
+
+- 默认查询最近 24 小时数据。
+- 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。
+
+**示例**
+
+```bash
+# 查看最近 24 小时监控
+bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx
+
+# 指定日期范围
+bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/knowledge-cli-guide.md b/docs/knowledge/knowledge-cli-guide.md
new file mode 100644
index 00000000..04ae6394
--- /dev/null
+++ b/docs/knowledge/knowledge-cli-guide.md
@@ -0,0 +1,822 @@
+# `bl knowledge` 命令完整用法指南
+
+> `bl knowledge` / `kscli` 知识库 CLI 命令总览，覆盖全部 34 个子命令。完整参数与示例请参阅各子域手册。
+
+---
+
+## 目录
+
+1. [概述](#概述)
+2. [核心概念与实体关系](#核心概念与实体关系)
+3. [通用约定](#通用约定)
+4. [典型工作流](#典型工作流)
+5. [命令手册](#命令手册)
+   - [知识库管理](#知识库管理) → [完整手册](knowledge/kb.md)
+   - [文档管理](#文档管理) → [完整手册](knowledge/doc.md)
+   - [检索服务管理](#检索服务管理) → [完整手册](knowledge/service.md)
+   - [Chunk 管理](#chunk-管理) → [完整手册](knowledge/chunk.md)
+   - [数据中心文件管理](#数据中心文件管理) → [完整手册](knowledge/file.md)
+   - [数据中心集合与分类](#数据中心集合与分类) → [完整手册](knowledge/collection-category.md)
+   - [检索与对话](#检索与对话) → [完整手册](knowledge/search-chat.md)
+6. [常见错误与排查](#常见错误与排查)
+7. [附录：命令速查表](#附录命令速查表)
+
+---
+
+## 概述
+
+`bl knowledge` 是阿里云百炼 CLI 的知识库命令组，覆盖 RAG（检索增强生成）全链路能力：
+
+- **知识库全生命周期管理**：创建、查看、更新、删除、监控
+- **文档管理**：上传本地文件、从 OSS 批量导入、查看解析状态、删除、打标签
+- **Chunk 级运维**：直接增删改查知识库中的内容切片
+- **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
+- **数据中心管理**：文件、集合（connector）、分类的增删查
+- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
+
+共 34 个子命令，按功能域分为 7 组。所有命令均使用 DashScope API Key 鉴权。
+
+---
+
+## 核心概念与实体关系
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     数据中心 (Data Center)                    │
+│                                                             │
+│  集合 (Collection) ──┬── 分类 (Category) ── 文件 (File)      │
+│                      │   "connector"        可多级嵌套       │
+│                      └── 默认分类                              │
+│                                                             │
+│  文件来源：doc upload(本地上传) / doc import-oss(OSS导入)     │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 导入 (import job)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    知识库 (Knowledge Base)                    │
+│                                                             │
+│  知识库 (KB / pipeline / index)                              │
+│    ├── 文档 (Doc) ── 解析状态: PENDING/RUNNING/COMPLETED     │
+│    │     └── Chunk ── 内容切片，可增删改查、排除/恢复检索     │
+│    └── 索引设置 (immutable): 向量模型、切片大小等             │
+│                                                             │
+│  知识库管理命令: create / list / info / update / delete / stats │
+└──────────────────────────┬──────────────────────────────────┘
+                           │ 绑定 (agent_config.kb_search_configs)
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  检索服务 (Service / Agent)                   │
+│                                                             │
+│  Service (agent)                                            │
+│    ├── scene: chat (Q&A) 或 search (检索)                    │
+│    ├── 版本: beta (草稿) → 1, 2, 3... (已发布)               │
+│    ├── 状态: draft → deployed → edited → deleted            │
+│    └── 配置: 模型、温度、策略、rerank 等                      │
+│                                                             │
+│  消费方式: search (语义检索) / chat (多轮对话)               │
+│  管理命令: create / update / deploy / copy / delete / list / get │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**关键关系**：
+
+- **数据中心文件 → 知识库**：通过 `knowledge create --doc-id` 或 `knowledge doc upload --index-id` 导入，文件解析后自动生成 chunk
+- **知识库 → 检索服务**：一个服务可绑定多个知识库，服务配置中 `kb_search_configs` 指定关联的知识库 ID
+- **检索服务 → 检索/对话**：`search` 和 `chat` 命令通过 `--agent-id` 指定服务来执行检索或对话
+
+---
+
+## 通用约定
+
+### 鉴权
+
+所有 `bl knowledge` 命令均使用 **DashScope API Key**（Bearer token）鉴权。获取方式：百炼控制台 API Key 页面。
+
+优先级（高 → 低）：
+
+1. `--api-key <key>` 命令行参数
+2. `DASHSCOPE_API_KEY` 环境变量
+3. 配置文件中的 `api_key`（`bl config set api_key <key>`）
+
+### Workspace ID
+
+知识库 API 使用 workspace 级域名（`{workspaceId}.cn-beijing.maas.aliyuncs.com`），因此 **几乎所有 knowledge 命令都需要 workspace ID**。
+
+优先级（高 → 低）：
+
+1. `--workspace-id <id>` 命令行参数
+2. `BAILIAN_WORKSPACE_ID` 环境变量
+3. 配置文件中的 `workspace_id`（`bl config set workspace_id <id>`）
+
+缺失时报错：`Workspace ID is required.`
+
+### 全局通用参数
+
+以下参数在所有 `bl knowledge` 子命令中通用，后续命令手册中不再逐条列出：
+
+| 参数                  | 类型   | 说明                                                        |
+| --------------------- | ------ | ----------------------------------------------------------- |
+| `--output <format>`   | string | 输出格式：`text`（默认，人类友好）或 `json`（API 原始响应） |
+| `--api-key <key>`     | string | DashScope API Key                                           |
+| `--base-url <url>`    | string | API 基地址（一般不需要指定）                                |
+| `--timeout <seconds>` | number | 请求超时秒数                                                |
+| `--quiet`             | switch | 静默模式，只输出关键结果（如 ID 列表）                      |
+| `--verbose`           | switch | 详细模式，打印 HTTP 请求/响应详情到 stderr                  |
+| `--dry-run`           | switch | 干跑模式，预览将发送的请求结构，不实际调用 API              |
+| `--config <name>`     | string | 使用指定配置 profile 执行命令                               |
+
+> **注意**：命令手册中每个命令的参数表只列出该命令**特有**的参数。上述全局参数对所有命令有效。
+
+### 输出格式约定
+
+- **text 模式**（默认）：人类友好的表格/结构化文本，适合终端查看。不同命令的输出格式见各命令的「输出」部分。
+- **json 模式**（`--output json`）：返回 API 原始 JSON 响应，适合程序化处理和 agent 解析。
+- **quiet 模式**（`--quiet`）：只输出最精简的结果（通常只有 ID），适合管道串联。
+
+### 危险操作确认
+
+涉及删除的命令（`kb delete`、`doc delete`、`chunk delete`、`file delete`、`category delete`、`service delete`、`service deploy`）在执行前会弹出二次确认提示。使用 `--yes` 可跳过确认，适用于自动化脚本。
+
+### Dry-run 模式
+
+`--dry-run` 模式下，命令会输出将发送的 endpoint 和 request body，但**不实际发起网络请求**。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。
+
+---
+
+## 典型工作流
+
+### 场景 A：从零搭建知识库并检索
+
+```bash
+# 1. 上传本地文件到数据中心，同时导入到新知识库
+bl knowledge doc upload --file ./docs/intro.md --workspace-id ws-xxx
+# → 返回 file-id
+
+# 2. 用文件创建知识库
+bl knowledge create --name my-kb --doc-id file-xxx --workspace-id ws-xxx --wait
+# → 返回 index-id (pipelineId) 和导入任务状态
+
+# 3. 创建检索服务（search 场景）
+bl knowledge service create --name my-search --scene search --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 agent-id
+
+# 4. 部署服务
+bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx --yes
+
+# 5. 执行检索
+bl knowledge search --query "什么是RAG" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+### 场景 B：上传目录并导入到已有知识库
+
+```bash
+# 1. 上传整个目录到数据中心并直接导入到知识库（一步到位）
+bl knowledge doc upload --file ./docs/ --index-id idx-xxx --workspace-id ws-xxx --wait
+# → 文件逐个上传到 OSS → 注册到数据中心 → 创建合并导入任务 → 轮询到完成
+
+# 2. 检查文档状态
+bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
+# → 查看 doc_id 和解析状态
+
+# 3. 如果有文档解析失败，查看导入任务详情
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+```
+
+### 场景 C：创建并部署 Q&A 服务
+
+```bash
+# 1. 创建 chat 场景的检索服务
+bl knowledge service create --name my-qa --scene chat --index-id idx-xxx --workspace-id ws-xxx
+# → 初始状态: draft, 版本: beta
+
+# 2. 调整配置（如修改模型、温度）
+bl knowledge service update --agent-id aid-xxx --model qwen-max --temperature 0.7 --workspace-id ws-xxx
+
+# 3. 用 beta 版本测试
+bl knowledge chat --message "什么是RAG?" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+
+# 4. 测试通过后发布
+bl knowledge service deploy --agent-id aid-xxx --version-desc "首版" --workspace-id ws-xxx --yes
+```
+
+### 场景 D：知识库内容运维
+
+```bash
+# 1. 查看 chunk 列表
+bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
+# → 返回 metadata._id (chunk id) 和 metadata.doc_id (document id)
+
+# 2. 修改 chunk 内容
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "修正后的内容" --workspace-id ws-xxx
+
+# 3. 排除某个 chunk 不参与检索（不删除内容）
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude --workspace-id ws-xxx
+
+# 4. 手动添加新 chunk
+bl knowledge chunk add --index-id idx-xxx --content "新增的知识片段" --title "补充说明" --workspace-id ws-xxx
+
+# 5. 删除 chunk（批量，自动分批每 10 个一组）
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes --workspace-id ws-xxx
+```
+
+### 场景 E：服务迁移/复用
+
+```bash
+# 1. 复制现有服务为新草稿
+bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
+# → 返回新的 agent-id，名称加 copy_ 前缀
+
+# 2. 修改新服务配置
+bl knowledge service update --agent-id aid-new --name "改进版" --temperature 0.5 --workspace-id ws-xxx
+
+# 3. 测试并发布
+bl knowledge chat --message "测试" --agent-id aid-new --agent-version beta --workspace-id ws-xxx
+bl knowledge service deploy --agent-id aid-new --workspace-id ws-xxx --yes
+```
+
+### 场景 F：从 OSS 批量导入文件
+
+```bash
+# 1. 从已授权的 OSS bucket 批量导入文件到数据中心
+bl knowledge doc import-oss \
+  --bucket my-bucket --region cn-beijing \
+  --oss-key docs/a.pdf --oss-key docs/b.docx \
+  --workspace-id ws-xxx
+# → 返回各文件的 fileId
+
+# 2. 创建知识库并导入这些文件
+bl knowledge create --name oss-kb --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
+
+# 3. 检索
+bl knowledge search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+---
+
+## 命令手册
+
+以下按功能域分组，覆盖全部 34 个子命令。每个条目包含功能说明、用法签名（kscli 前缀）和详细手册链接。
+
+> 完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。子域手册中的用法签名使用 `bl knowledge` 前缀。
+
+---
+
+### 知识库管理
+
+> 📖 [完整手册](knowledge/kb.md) — 6 个命令
+
+#### `kscli kb list`
+
+列出工作区中的知识库。
+
+```bash
+kscli kb list [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-list)
+
+---
+
+#### `kscli kb info`
+
+查看知识库配置详情。
+
+```bash
+kscli kb info --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-info)
+
+---
+
+#### `kscli kb create`
+
+创建知识库并导入数据中心文件或分类。
+
+```bash
+kscli kb create --name <text> (--doc-id <id> | --category-id <id>) [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-create)
+
+---
+
+#### `kscli kb update`
+
+更新知识库名称、描述或 rerank 阈值。
+
+```bash
+kscli kb update --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-update)
+
+---
+
+#### `kscli kb delete`
+
+删除知识库及其所有文档和 chunk。
+
+```bash
+kscli kb delete --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-delete)
+
+---
+
+#### `kscli kb stats`
+
+查看知识库存储和 QPS 监控数据。
+
+```bash
+kscli kb stats --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/kb.md#bl-knowledge-stats)
+
+---
+
+### 文档管理
+
+> 📖 [完整手册](knowledge/doc.md) — 6 个命令
+
+#### `kscli doc list`
+
+列出知识库中的文档及其解析/索引状态。
+
+```bash
+kscli doc list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-list)
+
+---
+
+#### `kscli doc status`
+
+查看知识库导入任务状态。
+
+```bash
+kscli doc status --index-id <id> --job-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-status)
+
+---
+
+#### `kscli doc upload`
+
+上传本地文件或目录到数据中心，可选导入到知识库。
+
+```bash
+kscli doc upload --file <path> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-upload)
+
+---
+
+#### `kscli doc delete`
+
+从知识库中删除文档及其 chunk。
+
+```bash
+kscli doc delete --index-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-delete)
+
+---
+
+#### `kscli doc tag`
+
+批量更新数据中心文件的标签。
+
+```bash
+kscli doc tag --doc-id <id> --tag <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-tag)
+
+---
+
+#### `kscli doc import-oss`
+
+从已授权的 OSS bucket 批量导入文件到数据中心。
+
+```bash
+kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
+```
+
+→ [完整参数与示例](knowledge/doc.md#bl-knowledge-doc-import-oss)
+
+---
+
+### 检索服务管理
+
+> 📖 [完整手册](knowledge/service.md) — 7 个命令
+
+#### `kscli service list`
+
+列出工作区中的检索/Q&A 服务。
+
+```bash
+kscli service list --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-list)
+
+---
+
+#### `kscli service get`
+
+查看服务详情，含各版本配置。
+
+```bash
+kscli service get --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-get)
+
+---
+
+#### `kscli service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+```bash
+kscli service create --name <text> --scene <chat|search> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-create)
+
+---
+
+#### `kscli service update`
+
+更新服务名称、描述或草稿配置。
+
+```bash
+kscli service update --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-update)
+
+---
+
+#### `kscli service deploy`
+
+发布 beta 草稿为新版本。
+
+```bash
+kscli service deploy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-deploy)
+
+---
+
+#### `kscli service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+```bash
+kscli service delete --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-delete)
+
+---
+
+#### `kscli service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+```bash
+kscli service copy --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/service.md#bl-knowledge-service-copy)
+
+---
+
+### Chunk 管理
+
+> 📖 [完整手册](knowledge/chunk.md) — 4 个命令
+
+#### `kscli chunk add`
+
+直接向知识库添加 chunk。
+
+```bash
+kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-add)
+
+---
+
+#### `kscli chunk list`
+
+列出知识库中的 chunk，含内容和状态。
+
+```bash
+kscli chunk list --index-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-list)
+
+---
+
+#### `kscli chunk update`
+
+更新 chunk 内容或切换其检索可见性。
+
+```bash
+kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-update)
+
+---
+
+#### `kscli chunk delete`
+
+从知识库中删除 chunk（不可逆）。
+
+```bash
+kscli chunk delete --index-id <id> --chunk-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/chunk.md#bl-knowledge-chunk-delete)
+
+---
+
+### 数据中心文件管理
+
+> 📖 [完整手册](knowledge/file.md) — 3 个命令
+
+#### `kscli file list`
+
+列出数据中心分类下的文件。
+
+```bash
+kscli file list --category-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-list)
+
+---
+
+#### `kscli file get`
+
+查看数据中心文件详情。
+
+```bash
+kscli file get --file-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-get)
+
+---
+
+#### `kscli file delete`
+
+从数据中心永久删除文件。
+
+```bash
+kscli file delete --file-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/file.md#bl-knowledge-file-delete)
+
+---
+
+### 数据中心集合与分类
+
+> 📖 [完整手册](knowledge/collection-category.md) — 5 个命令
+
+#### `kscli collection create`
+
+创建 FILE 数据集合。
+
+```bash
+kscli collection create --name <text> --description <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-create)
+
+---
+
+#### `kscli collection get`
+
+查看数据集合详情。
+
+```bash
+kscli collection get (--collection-id <id> | --name <text>) [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-collection-get)
+
+---
+
+#### `kscli category list`
+
+列出数据中心分类。
+
+```bash
+kscli category list [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-list)
+
+---
+
+#### `kscli category add`
+
+创建数据中心分类。
+
+```bash
+kscli category add --name <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-add)
+
+---
+
+#### `kscli category delete`
+
+删除数据中心分类。
+
+```bash
+kscli category delete --category-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/collection-category.md#bl-knowledge-category-delete)
+
+---
+
+### 检索与对话
+
+> 📖 [完整手册](knowledge/search-chat.md) — 3 个命令
+
+#### `kscli retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+```bash
+kscli retrieve --index-id <id> --query <text> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-retrieve)
+
+---
+
+#### `kscli search`
+
+对知识库执行语义检索（RAG 检索）。
+
+```bash
+kscli search --query <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-search)
+
+---
+
+#### `kscli chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+```bash
+kscli chat --message <text> --agent-id <id> [flags]
+```
+
+→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-chat)
+
+---
+
+## 常见错误与排查
+
+### Workspace ID 缺失
+
+**报错**：`Workspace ID is required.`
+
+**原因**：所有 knowledge 管理命令都需要 workspace ID 来构造 API 端点（`{workspaceId}.cn-beijing.maas.aliyuncs.com`）。
+
+**解决**：
+
+```bash
+# 方式1：命令行参数
+bl knowledge list --workspace-id ws-xxx
+
+# 方式2：环境变量
+export BAILIAN_WORKSPACE_ID=ws-xxx
+
+# 方式3：配置文件
+bl config set workspace_id ws-xxx
+```
+
+### 知识库 ID 不存在
+
+**报错**：`Knowledge base not found: idx-xxx`
+
+**原因**：`--index-id` 指定的知识库在当前 workspace 中不存在。
+
+**解决**：先 `bl knowledge list` 确认知识库 ID。
+
+### 导入任务 SystemError
+
+**报错**：服务端返回 `SystemError`
+
+**原因**：`doc status` 传入了不存在的 job ID，或知识库空闲无任务。
+
+**解决**：检查 `doc list` 输出中的 `ingestionId`，或从 `doc upload`/`knowledge create` 的返回值获取。
+
+### doc_id 与 fileId 混淆
+
+**问题**：`doc delete` 时用了 `doc upload` 返回的 `fileId` 而非 `doc list` 返回的 `doc_id`。
+
+**原因**：通过 `knowledge create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；但通过 `doc upload --index-id` 导入的，`doc_id` 可能含 workspace 后缀。
+
+**解决**：始终用 `doc list --quiet` 获取 `doc_id`。
+
+### retrieve 已废弃
+
+**问题**：`retrieve` 命令输出废弃警告。
+
+**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
+
+### OSS 导入权限错误
+
+**报错**：服务端返回权限相关错误。
+
+**原因**：OSS bucket 未授权给平台服务角色。
+
+**解决**：检查 RAM 控制台中的 `AliyunServiceRoleForBailian` 角色是否已正确授权。
+
+### Chat SSE error
+
+**报错**：`Chat API error` + API error code。
+
+**原因**：流式对话过程中服务端返回 error 事件。
+
+**解决**：检查 `--agent-id` 是否存在、服务是否已部署、API Key 是否有效。错误消息和 code 原样透传，不二次包装。
+
+### file list 返回空
+
+**问题**：`file list --category-id default` 返回空列表。
+
+**原因**：与上传 API 不同，`file list` 不解析字面量 `default`，需要真实分类 ID。
+
+**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
+
+### 集合无法删除
+
+**问题**：没有 `collection delete` 命令。
+
+**原因**：暂不支持通过 CLI 删除。
+
+**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
+
+---
+
+## 附录：命令速查表
+
+| 命令                      | 功能         | 关键参数                                                    |
+| ------------------------- | ------------ | ----------------------------------------------------------- |
+| `kscli kb list`           | 列出知识库   | `--name`                                                    |
+| `kscli kb info`           | 知识库详情   | `--index-id`                                                |
+| `kscli kb create`         | 创建知识库   | `--name`, `--doc-id`/`--category-id`                        |
+| `kscli kb update`         | 更新知识库   | `--index-id`, `--name`/`--description`/`--rerank-min-score` |
+| `kscli kb delete`         | 删除知识库   | `--index-id`, `--yes`                                       |
+| `kscli kb stats`          | 监控数据     | `--index-id`, `--start`/`--end`                             |
+| `kscli doc list`          | 文档列表     | `--index-id`                                                |
+| `kscli doc status`        | 导入任务状态 | `--index-id`, `--job-id`, `--wait`                          |
+| `kscli doc upload`        | 上传文件     | `--file`, `--index-id`, `--wait`                            |
+| `kscli doc delete`        | 删除文档     | `--index-id`, `--doc-id`                                    |
+| `kscli doc tag`           | 文件打标签   | `--doc-id`, `--tag`, `--mode`                               |
+| `kscli doc import-oss`    | OSS 导入     | `--bucket`, `--region`, `--oss-key`                         |
+| `kscli service list`      | 服务列表     | `--scene`                                                   |
+| `kscli service get`       | 服务详情     | `--agent-id`                                                |
+| `kscli service create`    | 创建服务     | `--name`, `--scene`, `--index-id`                           |
+| `kscli service update`    | 更新服务     | `--agent-id`, 配置参数                                      |
+| `kscli service deploy`    | 发布服务     | `--agent-id`, `--yes`                                       |
+| `kscli service delete`    | 删除服务     | `--agent-id`, `--yes`                                       |
+| `kscli service copy`      | 复制服务     | `--agent-id`                                                |
+| `kscli chunk add`         | 添加 chunk   | `--index-id`, `--content`/`--field`                         |
+| `kscli chunk list`        | chunk 列表   | `--index-id`, `--doc-id`                                    |
+| `kscli chunk update`      | 更新 chunk   | `--index-id`, `--chunk-id`, `--doc-id`                      |
+| `kscli chunk delete`      | 删除 chunk   | `--index-id`, `--chunk-id`, `--yes`                         |
+| `kscli file list`         | 文件列表     | `--category-id`                                             |
+| `kscli file get`          | 文件详情     | `--file-id`                                                 |
+| `kscli file delete`       | 删除文件     | `--file-id`, `--yes`                                        |
+| `kscli collection create` | 创建集合     | `--name`, `--description`                                   |
+| `kscli collection get`    | 集合详情     | `--collection-id`/`--name`                                  |
+| `kscli category list`     | 分类列表     | `--collection-id`, `--parent-id`                            |
+| `kscli category add`      | 创建分类     | `--name`, `--parent-id`                                     |
+| `kscli category delete`   | 删除分类     | `--category-id`, `--yes`                                    |
+| `kscli retrieve`          | 检索（废弃） | `--index-id`, `--query`                                     |
+| `kscli search`            | 语义检索     | `--query`, `--agent-id`                                     |
+| `kscli chat`              | RAG 对话     | `--message`, `--agent-id`                                   |
diff --git a/docs/knowledge/search-chat.md b/docs/knowledge/search-chat.md
new file mode 100644
index 00000000..2a02db5c
--- /dev/null
+++ b/docs/knowledge/search-chat.md
@@ -0,0 +1,218 @@
+# 检索与对话命令手册
+
+以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge retrieve`
+
+从知识库检索（已废弃，请用 `search` 替代）。
+
+**用法**
+
+```bash
+bl knowledge retrieve --index-id <id> --query <text> [flags]
+```
+
+**参数**
+
+| 参数                            | 类型   | 必填 | 说明                                                |
+| ------------------------------- | ------ | ---- | --------------------------------------------------- |
+| `--index-id <id>`               | string | 是   | 知识库 ID                                           |
+| `--query <text>`                | string | 是   | 检索查询文本                                        |
+| `--dense-similarity-top-k <n>`  | number | 否   | 稠密检索 top K                                      |
+| `--sparse-similarity-top-k <n>` | number | 否   | 稀疏检索 top K                                      |
+| `--rerank`                      | switch | 否   | 启用 rerank                                         |
+| `--rerank-top-n <n>`            | number | 否   | rerank 返回 top N 结果                              |
+| `--rerank-model <name>`         | string | 否   | rerank 模型名，如 `qwen3-rerank-hybrid`             |
+| `--rerank-mode <mode>`          | string | 否   | rerank 模式：`qa`、`similar` 或 `custom`            |
+| `--rerank-instruct <text>`      | string | 否   | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
+| `--top-k <n>`                   | number | 否   | 返回结果数（已废弃，用 `--rerank-top-n` 替代）      |
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
+- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
+- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
+
+**示例**
+
+```bash
+# 基础检索
+bl knowledge retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
+
+# 启用 rerank
+bl knowledge retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
+```
+
+---
+
+#### `bl knowledge search`
+
+对知识库执行语义检索（RAG 检索）。
+
+**用法**
+
+```bash
+bl knowledge search --query <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------- |
+| `--query <text>`            | string | 是   | 检索查询文本（不可为空）                                            |
+| `--agent-id <id>`           | string | 是   | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本  |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复），用于多模态检索                                  |
+
+**参数约束**
+
+- `--query` 不可为空（API 要求 `minLength: 1`）
+
+**输出**
+
+text/quiet 模式：
+
+```
+[1] (score: 0.9512)
+检索到的文本内容...
+
+[2] (score: 0.8734)
+另一段文本内容...
+```
+
+> 无结果时输出 `No results found.`
+
+json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
+
+**注意事项**
+
+- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
+- `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
+- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
+
+**示例**
+
+```bash
+# 基础检索
+bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态检索（带图片）
+bl knowledge search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
+
+# 调试草稿版本
+bl knowledge search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+#### `bl knowledge chat`
+
+与知识库进行 RAG 对话（流式输出）。
+
+**用法**
+
+```bash
+bl knowledge chat --message <text> --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                                                                                           |
+| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `--message <text>`          | array  | 是¹  | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
+| `--agent-id <id>`           | string | 是   | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看）                                               |
+| `--agent-version <version>` | string | 否   | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本                                                             |
+| `--image <url>`             | array  | 否   | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容                                                                     |
+
+> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
+
+**参数约束**
+
+- `--message` 或 `--image` 至少提供一个
+- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
+
+**输出**
+
+**TTY text 模式**（实时流式）：
+
+```
+🔍 Retrieving...
+✍️ Generating...
+这是AI生成的回答内容，逐字流式输出...
+```
+
+> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
+
+**非 TTY text 模式**（缓冲输出）：
+
+```
+完整的回答文本...
+```
+
+**json 模式**（`--output json`）：
+
+```json
+{
+  "answer": "完整的回答文本...",
+  "request_id": "xxx"
+}
+```
+
+quiet 模式：输出完整的回答文本。
+
+**注意事项**
+
+- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
+- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
+- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
+- `--agent-version beta` 调用草稿配置进行调试。
+- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
+- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
+
+**示例**
+
+```bash
+# 单轮对话
+bl knowledge chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多轮对话（带历史）
+bl knowledge chat \
+  --message "user:What is RAG?" \
+  --message "assistant:RAG is retrieval-augmented generation..." \
+  --message "How does it work?" \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 多模态对话（带图片）
+bl knowledge chat \
+  --message "Describe these images" \
+  --image https://example.com/a.png \
+  --image https://example.com/b.png \
+  --agent-id aid-xxx --workspace-id ws-xxx
+
+# 调试草稿版本
+bl knowledge chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/docs/knowledge/service.md b/docs/knowledge/service.md
new file mode 100644
index 00000000..d0d06372
--- /dev/null
+++ b/docs/knowledge/service.md
@@ -0,0 +1,401 @@
+# 检索服务管理命令手册
+
+检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
+
+> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
+
+---
+
+#### `bl knowledge service list`
+
+列出工作区中的检索/Q&A 服务。
+
+**用法**
+
+```bash
+bl knowledge service list --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                                    |
+| ------------------------ | ------ | ---- | ------------------------------------------------------- |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）              |
+| `--status <status>`      | string | 否   | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
+| `--name <text>`          | string | 否   | 按服务名称模糊过滤                                      |
+| `--agent-id <id>`        | string | 否   | 按精确 agent ID 过滤                                    |
+| `--index-id <id>`        | string | 否   | 按关联知识库 ID 过滤                                    |
+| `--page-number <n>`      | number | 否   | 页码（默认：1）                                         |
+| `--page-size <n>`        | number | 否   | 每页条数（默认：10，最大 100）                          |
+
+**参数约束**
+
+- `--scene` 只能是 `chat` 或 `search`
+- `--status` 只能是 `draft`、`deployed`、`deleted`
+- `--page-size` 范围 1-100
+
+**输出**
+
+text 模式：
+
+```
+aid-xxx  deployed  2  my-qa  (kb: my-kb)
+total: 1
+Use an agent_id above with the knowledge chat command.
+```
+
+> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
+
+quiet 模式：每行一个 `agent_id`。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
+
+**示例**
+
+```bash
+# 列出 chat 服务
+bl knowledge service list --scene chat --workspace-id ws-xxx
+
+# 只看已部署的检索服务
+bl knowledge service list --scene search --status deployed
+```
+
+---
+
+#### `bl knowledge service get`
+
+查看服务详情，含各版本配置。
+
+**用法**
+
+```bash
+bl knowledge service get --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                        | 类型   | 必填 | 说明                                                      |
+| --------------------------- | ------ | ---- | --------------------------------------------------------- |
+| `--agent-id <id>`           | string | 是   | 服务（agent）ID                                           |
+| `--agent-version <version>` | string | 否   | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
+
+**输出**
+
+text 模式：
+
+```
+Basic:
+  id: aid-xxx
+  name: my-qa
+  desc: product Q&A
+  scene: chat
+  status: deployed
+Version beta:
+  desc: draft
+  policy: turbo
+  model: qwen-max
+  temperature: 0.7
+  kb: idx-xxx (my-kb)
+Version 1:
+  published: 2026-01-01
+  ...
+```
+
+quiet 模式：输出 JSON 格式。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
+- 版本值原样传递，有效值集合由服务端维护。
+
+**示例**
+
+```bash
+# 查看服务完整详情
+bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx
+
+# 只看 beta 草稿配置
+bl knowledge service get --agent-id aid-xxx --agent-version beta
+```
+
+---
+
+#### `bl knowledge service create`
+
+创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
+
+**用法**
+
+```bash
+bl knowledge service create --name <text> --scene <chat|search> [flags]
+```
+
+**参数**
+
+| 参数                     | 类型   | 必填 | 说明                                              |
+| ------------------------ | ------ | ---- | ------------------------------------------------- |
+| `--name <text>`          | string | 是   | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
+| `--scene <chat\|search>` | string | 是   | 服务场景：`chat`（Q&A）或 `search`（检索）        |
+| `--description <text>`   | string | 否   | 服务描述（最多 1000 字符）                        |
+| `--index-id <id>`        | string | 否   | 绑定此知识库；其他配置使用服务端默认值            |
+
+**参数约束**
+
+- `--name` 最多 200 字符
+- `--scene` 只能是 `chat` 或 `search`
+- `--description` 最多 1000 字符
+
+**输出**
+
+text 模式：
+
+```
+created: aid-xxx  (status: draft, version: beta)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
+- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 创建 Q&A 服务
+bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx
+
+# 创建检索服务并绑定知识库
+bl knowledge service create --name my-search --scene search --index-id idx-xxx
+```
+
+---
+
+#### `bl knowledge service update`
+
+更新服务名称、描述或草稿配置。
+
+**用法**
+
+```bash
+bl knowledge service update --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                           | 类型   | 必填 | 说明                                                                                     |
+| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
+| `--agent-id <id>`              | string | 是   | 服务（agent）ID                                                                          |
+| `--name <text>`                | string | 否   | 新名称（最多 200 字符）                                                                  |
+| `--description <text>`         | string | 否   | 新描述（最多 1000 字符）                                                                 |
+| `--agent-version <version>`    | string | 否   | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`）                           |
+| `--version-desc <text>`        | string | 否   | 版本描述                                                                                 |
+| `--policy <policy>`            | string | 否   | Agent 策略：`turbo`（快速）或 `agentic`（多轮）                                          |
+| `--model <name>`               | string | 否   | 生成模型代码（须在平台白名单中）                                                         |
+| `--temperature <n>`            | number | 否   | 采样温度，范围 0-2                                                                       |
+| `--max-llm-calls <n>`          | number | 否   | 单次请求最大 LLM 调用次数，范围 1-30                                                     |
+| `--enable-session-file <bool>` | string | 否   | 启用会话文件：`true` 或 `false`                                                          |
+| `--enable-refusal <bool>`      | string | 否   | 启用拒答：`true` 或 `false`                                                              |
+| `--enable-anti-leak <bool>`    | string | 否   | 启用防泄漏：`true` 或 `false`                                                            |
+| `--enable-rich-text <bool>`    | string | 否   | 启用富文本输出：`true` 或 `false`                                                        |
+| `--enable-citation <bool>`     | string | 否   | 启用引用标注：`true` 或 `false`                                                          |
+| `--config-file <path>`         | string | 否   | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
+
+**参数约束**
+
+- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
+- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
+- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
+- `--name` 最多 200 字符；`--description` 最多 1000 字符
+- `--policy` 只能是 `turbo` 或 `agentic`
+- `--temperature` 范围 0-2
+- `--max-llm-calls` 范围 1-30
+- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
+
+**输出**
+
+text 模式：
+
+```
+updated: aid-xxx
+Draft config changed — verify with --agent-version beta, then deploy.
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
+- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
+- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
+- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
+
+**示例**
+
+```bash
+# 调整温度
+bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
+
+# 用 JSON 文件替换整个配置
+bl knowledge service update --agent-id aid-xxx --config-file ./agent-config.json
+
+# 给已发布版本 1 加描述
+bl knowledge service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
+```
+
+---
+
+#### `bl knowledge service deploy`
+
+发布 beta 草稿为新版本。
+
+**用法**
+
+```bash
+bl knowledge service deploy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数                    | 类型   | 必填 | 说明             |
+| ----------------------- | ------ | ---- | ---------------- |
+| `--agent-id <id>`       | string | 是   | 服务（agent）ID  |
+| `--version-desc <text>` | string | 否   | 新版本的描述说明 |
+| `--yes`                 | switch | 否   | 跳过确认提示     |
+
+**输出**
+
+text 模式：
+
+```
+deployed: aid-xxx  version 2
+```
+
+quiet 模式：输出新版本号。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 版本号自动递增，状态变为 `deployed`。
+- 发布影响线上调用方，确认提示会警告。
+- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
+- 需要工作区的知识库修改权限。
+
+**示例**
+
+```bash
+# 发布（交互确认）
+bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx
+
+# 带描述并跳过确认
+bl knowledge service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
+```
+
+---
+
+#### `bl knowledge service delete`
+
+删除检索/Q&A 服务（软删除，幂等）。
+
+**用法**
+
+```bash
+bl knowledge service delete --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明            |
+| ----------------- | ------ | ---- | --------------- |
+| `--agent-id <id>` | string | 是   | 服务（agent）ID |
+| `--yes`           | switch | 否   | 跳过确认提示    |
+
+**输出**
+
+text 模式：
+
+```
+deleted: aid-xxx  (status: deleted)
+```
+
+quiet 模式：无输出。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
+- API 是幂等的：删除已删除的服务不会报错。
+- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
+- 需要工作区的知识库删除权限。
+
+**示例**
+
+```bash
+# 删除（交互确认）
+bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx
+
+# 跳过确认
+bl knowledge service delete --agent-id aid-xxx --yes
+```
+
+---
+
+#### `bl knowledge service copy`
+
+复制服务为新草稿（名称自动加 `copy_` 前缀）。
+
+**用法**
+
+```bash
+bl knowledge service copy --agent-id <id> [flags]
+```
+
+**参数**
+
+| 参数              | 类型   | 必填 | 说明              |
+| ----------------- | ------ | ---- | ----------------- |
+| `--agent-id <id>` | string | 是   | 源服务（agent）ID |
+
+**输出**
+
+text 模式：
+
+```
+new agent_id: aid-new  (name: copy_my-qa, status: draft)
+Test the draft with --agent-version beta on search/chat, then deploy it to publish.
+```
+
+quiet 模式：输出新 agent ID。
+
+json 模式：返回 API 原始响应。
+
+**注意事项**
+
+- 副本初始为 beta 草稿，测试后需 deploy 发布。
+- 需要工作区的知识库创建权限。
+
+**示例**
+
+```bash
+# 复制服务
+bl knowledge service copy --agent-id aid-source --workspace-id ws-xxx
+```
+
+---
+
+← [返回总览](../knowledge-cli-guide.md)
diff --git a/package.json b/package.json
index c631a0b9..a120ae71 100644
--- a/package.json
+++ b/package.json
@@ -21,6 +21,7 @@
     "bl": "pnpm -F bailian-cli dev",
     "kscli": "pnpm -F knowledge-studio-cli dev",
     "test": "vp test",
+    "test:journey": "vp test packages/commands/tests/e2e/knowledge/journeys",
     "release:check": "node tools/release/check.mjs",
     "wiki:crawl": "node tools/wiki-crawler/index.mjs",
     "test:stress": "node packages/cli/tests/stress/run.mjs"
diff --git a/packages/cli/doc-commands.md b/packages/cli/doc-commands.md
new file mode 100644
index 00000000..f2f57b94
--- /dev/null
+++ b/packages/cli/doc-commands.md
@@ -0,0 +1,160 @@
+# 迭代一设计 · doc 组命令
+
+> 命令：`doc upload` / `doc list` / `doc status` / `doc delete` / `doc tag` / `doc import-oss`
+> 公共约定见 [README.md](README.md)。
+
+## doc upload — 上传本地文件入库（编排命令）
+
+**说明**：本迭代最复杂命令。把"本地文件 → 数据中心 →（可选）导入知识库"封装为一条命令，替代构建期最高频的控制台操作（S2.2 痛点:高）。对标竞品 add-file。
+
+**编排四步**：
+
+| 步                                 | API                                                | 输入                                                                          | 输出                                   |
+| ---------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------- |
+| 1 申请租约                         | `POST /api/v1/connector/dash/applyFileUploadLease` | `category`(类目ID) + `fileName` + `sizeBytes`(字符串!) + `contentMd5`(Base64) | `leaseId` + `param.url/method/headers` |
+| 2 OSS 上传                         | `PUT {param.url}`                                  | 文件二进制 + `param.headers`（含 `x-bailian-extra`、`Content-Type`）          | HTTP 200                               |
+| 3 注册文件                         | `POST /api/v1/connector/dash/addFile`              | `leaseId` + `category` + `parser: "AUTO_SELECT"` + `tags?`                    | `fileId`                               |
+| 4 导入（可选，传 `--index-id` 时） | `POST /api/v1/indices/rag/index/job/create`        | `indexId` + `dataSource: { sourceType: "DATA_CENTER_FILE", fileIds }`         | `ingestionId`                          |
+
+坑位（实现注释必须标注）：
+
+- `sizeBytes` 必须字符串；`contentMd5` = `crypto.createHash("md5").update(buf).digest("base64")`
+- 租约/注册的类目参数名是 `category`，不是 `categoryId`
+- 第 4 步 body 是嵌套 `dataSource: { sourceType, fileIds }`（实测；公开文档的平铺 `documentIds` 会报 `Index.InvalidParameter`）
+- **第 4 步必须显式传 `sourceType`，不传会导入整个数据中心（API 文档明示的默认行为）**
+- 步骤 2 走 OSS 域名不走 DashScope 网关，用原生 fetch 而非 ctx.client（无 Bearer 头）；失败归类 NETWORK
+
+**Flags**：
+
+| flag                                               | 类型   | 必填 | 说明                                                                                                                  |
+| -------------------------------------------------- | ------ | ---- | --------------------------------------------------------------------------------------------------------------------- |
+| `--file <path>`                                    | array  | 是   | 本地文件路径，可重复；扩展名与大小按产品支持范围预校验（见下方格式白名单）                                            |
+| `--index-id <id>`                                  | string | 否   | 注册后立即导入该知识库（触发第 4 步，多文件合并为一个 job）                                                           |
+| `--category-id <id>`                               | string | 否   | 目标类目；缺省自动解析默认类目（listCategory 取 `isDefault: true`），解析失败报 GENERAL + hint 显式传 `--category-id` |
+| `--tag <text>`                                     | array  | 否   | addFile tags，可重复                                                                                                  |
+| `--wait` / `--poll-interval <s>` / `--timeout <s>` | —      | 否   | 与 `--index-id` 联用，轮询 job status 至终态                                                                          |
+
+**validate**：`--wait` 无 `--index-id` → USAGE；文件不存在/不可读 → GENERAL + errno hint（沿用错误边界规范）。
+
+**格式白名单与大小预校验**（依据 data/documents.md「支持的格式」，读文件前拦截，避免白传 OSS）：
+
+| 类型   | 扩展名                     | 硬限（超限 USAGE）                                    |
+| ------ | -------------------------- | ----------------------------------------------------- |
+| 文档   | .doc .docx .ppt .pptx .pdf | 150 MB                                                |
+| 表格   | .xls .xlsx                 | 10 MB（产品为“建议值”，超限降级为 stderr 警告不拦截） |
+| 图片   | .png .jpg .jpeg .bmp .gif  | 20 MB（尺寸约束不做客户端校验，留服务端）             |
+| 纯文本 | .md .txt .html             | 10 MB（同表格，警告不拦截）                           |
+
+- 扩展名不在白名单 → USAGE，错误信息列出支持格式；白名单常量独立导出便于后续随产品更新
+- 开放问题：create-kb.md 提及 .csv 但 documents.md 格式表未列——文档口径不一致，实现前向产品确认；确认前 .csv 暂入白名单（服务端拒绝会透传）
+
+**输出**：
+
+- text：每文件一行 `<fileName>  <fileId>  registered`；有导入时追加 `job: <ingestionId>`；--wait 结束追加终态
+- json：`{ files: [{path, fileId}], index_id?, ingestion_id?, final_status? }`（编排命令无单一响应可透传，输出自定义稳定结构）
+- quiet：仅 fileId 每行一个
+
+**实现方案**：
+
+- 文件 `doc-upload.ts`；多文件串行执行 1-3 步（首版不并发，避免 OSS 限流复杂化），全部注册成功后合并执行第 4 步
+- 部分失败语义：任一文件步骤 1-3 失败即中止并报错，已成功的 fileId 列入错误 hint（幂等重传代价低）
+- 默认类目解析结果进程内缓存（多文件只查一次）
+- dry-run：不读文件内容（size/md5 以占位符表示），输出四步编排计划 `{ steps: [{step, endpoint, request}] }`
+
+**测试方案**：
+
+- help / 缺 `--file` exitCode 2 / `--wait` 无 `--index-id` exitCode 2
+- 文件不存在 → 非零退出 + ENOENT hint；`.zip` 扩展名 → USAGE 列出支持格式
+- dry-run：断言 steps 长度（带/不带 --index-id 为 4/3）、lease 请求 `sizeBytes` 为字符串类型、job 请求含 `sourceType: "DATA_CENTER_FILE"`
+- live：上传 1KB 临时 md 文件 → 断言 fileId 前缀 `file_` → afterAll doc delete + 数据中心 deleteFile 清理
+
+## doc list — 查询知识库文档列表
+
+**说明**：列出库内文档及解析/索引状态，含 FAILED 发现（S2.3 / S5.2）。
+
+**API**：`GET /api/v1/indices/rag/index/files`，query string：`index_id` + `page_num`（注意本接口是 page_num）+ `page_size`（默认 10，最大 100）。
+
+**Flags**：`--index-id` 必填；`--page-number` / `--page-size`。
+
+**输出**：
+
+- text：每行 `doc_id  status  doc_name  doc_type  size`；status=FAILED 行红色高亮（TTY）；尾行 `total: N`
+- json 透传；quiet 仅 doc_id
+
+**实现/测试**：单 API 直映射（`doc-list.ts`）；dry-run 断言 query 参数名为 `page_num`；live 断言 rows 结构与 doc_id 前缀。
+
+## doc status — 查询导入任务状态
+
+**说明**：查导入任务进度，`--wait` 阻塞至终态供脚本串行（S2.3 痛点:高，L3 验收：FAILED 时非零 exit code）。
+
+**API**：`GET /api/v1/indices/rag/index_job/status`，query string：`index_id` + `job_id`（**双必填，仅传其一服务端返回 SystemError，客户端前置双校验拦截**）+ 分页参数。
+
+**Flags**：
+
+| flag                                                                 | 必填 | 说明                                                                                    |
+| -------------------------------------------------------------------- | ---- | --------------------------------------------------------------------------------------- |
+| `--index-id <id>`                                                    | 是   | 知识库 ID                                                                               |
+| `--job-id <id>`                                                      | 是   | 导入任务 ID（kb create / doc upload 返回的 ingestionId；也见 doc list 的 ingestion_id） |
+| `--page-number` / `--page-size`                                      | 否   | 任务含大量文档时分页                                                                    |
+| `--wait` / `--poll-interval <s>`(默认 5) / `--timeout <s>`(默认 600) | 否   | 轮询至终态                                                                              |
+
+**行为**：
+
+- 终态 FINISH → exit 0；FAILED → `BailianError(GENERAL)` 透传服务端 message（含文档级失败明细摘要），exit 1
+- `--wait` 超时 → TIMEOUT(5)
+- 已知行为：库无进行中任务时接口可能返回 SystemError——hint 引导 "check ingestion_id via doc list"
+
+**输出**：text 顶部任务总状态 + 文档级状态列表（FAILED 高亮）；json 透传。
+
+**测试方案**：help / 缺任一必填（两条用例）/ dry-run 断言 query 含两个 id / live：配合 upload 用例拿真实 job 轮询到 FINISH；`--wait --timeout 1` 对慢任务断言 exitCode 5（若不稳定则仅静态覆盖超时路径，live 标记 skip 原因）。
+
+## doc delete — 删除文档【危险操作】
+
+**说明**：从知识库删除文档及其全部切片（S5.1 内容更新循环）。
+
+**API**：`POST /api/v1/indices/rag/index/delete_file`，body `{ index_id, doc_ids }`（snake_case）。响应 `data.deleted[]` 为实际删除列表。
+
+**Flags**：`--index-id` 必填；`--doc-id` array 必填（可重复）；`--yes`。
+
+**实现方案**：`doc-delete.ts`；确认摘要含 index_id + doc_id 列表（≤5 个全列，超出显示前 5 + 总数）；输出以 `data.deleted` 为准（与入参数量不一致时 text 模式警告差异）。
+
+**测试方案**：help / 缺参×2 / dry-run 断言 `doc_ids` 数组 / 非 TTY 无 `--yes` exitCode 2 / live 配合 upload 清理链。
+
+## doc tag — 批量更新文档标签
+
+**说明**：批量打标，支撑标签过滤检索（S2.4）。
+
+**API**：`POST /api/v1/connector/dash/batchUpdateFileTag`。`fileInfos`（1-20 项，每项 `fileId` + `tags`，单标签 ≤32 字符、单文件 ≤100 个、总长 ≤700）+ `updateMode`（OVERWRITE/APPEND）。
+
+**Flags**：
+
+| flag            | 必填 | 说明                                                                      |
+| --------------- | ---- | ------------------------------------------------------------------------- |
+| `--doc-id <id>` | 是   | 可重复，1-20 个（客户端预校验），映射 fileInfos[].fileId                  |
+| `--tag <text>`  | 是   | 可重复，应用到所有 `--doc-id`（首版同一组标签批量打；异构标签用多次调用） |
+| `--mode <m>`    | 否   | choices: `overwrite`/`append`，默认 `append`（追加比覆盖安全，作为缺省）  |
+
+**实现/测试**：`doc-tag.ts` 单 API 直映射；客户端预校验标签长度约束（USAGE 前置拦截）；dry-run 断言 `updateMode: "APPEND"` 大写映射与 fileInfos 结构；live 打标后 listFile/describeFile 验证回读。
+
+## doc import-oss — 从授权 OSS 批量导入
+
+**说明**：从已 SLR 授权的 OSS Bucket 批量导入数据中心（大客户批量场景）。
+
+**API**：`POST /api/v1/connector/dash/addFilesFromAuthorizedOss`。必填 `categoryId/categoryType/ossBucket/ossRegionId/fileDetails`（1-10 项，每项 `fileName+ossKey`）。返回 `data.fileIds`。
+
+**Flags**：
+
+| flag                 | 必填 | 说明                                         |
+| -------------------- | ---- | -------------------------------------------- |
+| `--bucket <name>`    | 是   | 映射 ossBucket                               |
+| `--region <id>`      | 是   | 映射 ossRegionId（如 cn-beijing）            |
+| `--oss-key <key>`    | 是   | 可重复，1-10 个；fileName 取 key 的 basename |
+| `--category-id <id>` | 否   | 缺省走默认类目解析（复用 upload 的解析函数） |
+| `--tag <text>`       | 否   | 可重复，≤10                                  |
+| `--overwrite`        | 否   | switch，映射 overWriteFileByOssKey           |
+
+固定值：`categoryType: "UNSTRUCTURED"`；`parser` 不暴露（默认 AUTO_SELECT，审慎原则——DASH_QWEN_VL_PARSER 等需配 parserConfig，使用方式未验证）。
+
+**错误边界**：SLR 未授权的服务端权限错误原样透传，hint 附 RAM 控制台确认 `AliyunServiceRoleForBailian` 的指引（该指引来自 API 文档 Note，属可权威解释范围）。
+
+**实现/测试**：`doc-import-oss.ts` 单 API 直映射；dry-run 断言 fileDetails 结构与 fileName 派生逻辑；live 依赖 OSS 授权环境，gating 追加 `BAILIAN_E2E_OSS_BUCKET` 环境变量，无则 skip。
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 7c48be7d..c56ccadd 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
   "keywords": [
     "agent",
diff --git a/packages/cli/src/commands.ts b/packages/cli/src/commands.ts
index b772ba34..29160f68 100644
--- a/packages/cli/src/commands.ts
+++ b/packages/cli/src/commands.ts
@@ -33,6 +33,37 @@ import {
   knowledgeRetrieve,
   knowledgeSearch,
   knowledgeChat,
+  knowledgeKbList,
+  knowledgeKbInfo,
+  knowledgeDocList,
+  knowledgeDocStatus,
+  knowledgeDocUpload,
+  knowledgeKbCreate,
+  knowledgeKbUpdate,
+  knowledgeKbDelete,
+  knowledgeDocDelete,
+  knowledgeDocTag,
+  knowledgeServiceList,
+  knowledgeServiceGet,
+  knowledgeServiceCreate,
+  knowledgeServiceUpdate,
+  knowledgeServiceDeploy,
+  knowledgeServiceDelete,
+  knowledgeServiceCopy,
+  knowledgeChunkAdd,
+  knowledgeChunkList,
+  knowledgeChunkUpdate,
+  knowledgeChunkDelete,
+  knowledgeKbStats,
+  knowledgeCategoryList,
+  knowledgeCategoryAdd,
+  knowledgeCategoryDelete,
+  knowledgeFileList,
+  knowledgeFileGet,
+  knowledgeFileDelete,
+  knowledgeCollectionCreate,
+  knowledgeCollectionGet,
+  knowledgeDocImportOss,
   mcpCall,
   mcpList,
   mcpTools,
@@ -157,6 +188,39 @@ export const commands: Record<string, AnyCommand> = {
   "knowledge retrieve": knowledgeRetrieve,
   "knowledge search": knowledgeSearch,
   "knowledge chat": knowledgeChat,
+  "knowledge list": knowledgeKbList,
+  "knowledge info": knowledgeKbInfo,
+  "knowledge create": knowledgeKbCreate,
+  "knowledge update": knowledgeKbUpdate,
+  "knowledge delete": knowledgeKbDelete,
+  "knowledge doc list": knowledgeDocList,
+  "knowledge doc status": knowledgeDocStatus,
+  "knowledge doc upload": knowledgeDocUpload,
+  "knowledge doc delete": knowledgeDocDelete,
+  "knowledge doc tag": knowledgeDocTag,
+  "knowledge service list": knowledgeServiceList,
+  "knowledge service get": knowledgeServiceGet,
+  "knowledge service create": knowledgeServiceCreate,
+  "knowledge service update": knowledgeServiceUpdate,
+  "knowledge service deploy": knowledgeServiceDeploy,
+  "knowledge service delete": knowledgeServiceDelete,
+  "knowledge service copy": knowledgeServiceCopy,
+  "knowledge chunk add": knowledgeChunkAdd,
+  "knowledge chunk list": knowledgeChunkList,
+  "knowledge chunk update": knowledgeChunkUpdate,
+  "knowledge chunk delete": knowledgeChunkDelete,
+  "knowledge stats": knowledgeKbStats,
+  "knowledge doc import-oss": knowledgeDocImportOss,
+  // Data-center commands live under knowledge (no separate connector namespace);
+  // the user-facing term for connector is "collection".
+  "knowledge collection create": knowledgeCollectionCreate,
+  "knowledge collection get": knowledgeCollectionGet,
+  "knowledge category list": knowledgeCategoryList,
+  "knowledge category add": knowledgeCategoryAdd,
+  "knowledge category delete": knowledgeCategoryDelete,
+  "knowledge file list": knowledgeFileList,
+  "knowledge file get": knowledgeFileGet,
+  "knowledge file delete": knowledgeFileDelete,
   "mcp call": mcpCall,
   "mcp list": mcpList,
   "mcp tools": mcpTools,
diff --git a/packages/commands/package.json b/packages/commands/package.json
index 3cb48ff1..9f3ade0d 100644
--- a/packages/commands/package.json
+++ b/packages/commands/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-commands",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Command library for bailian-cli products (knowledge, memory, media, …). See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {
diff --git a/packages/commands/src/commands/knowledge/category-add.ts b/packages/commands/src/commands/knowledge/category-add.ts
new file mode 100644
index 00000000..57c25dcc
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/category-add.ts
@@ -0,0 +1,79 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAddCategoryResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const CATEGORY_ADD_FLAGS = {
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Category name (1-20 chars)",
+    required: true,
+  },
+  parentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Create as a sub-category of this category",
+  },
+  collectionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Create under this collection (defaults to the platform collection)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a data-center category",
+  auth: "apiKey",
+  usageArgs: "--name <text> [flags]",
+  flags: CATEGORY_ADD_FLAGS,
+  notes: ["Use categories to organize data-center files by business domain."],
+  exampleArgs: ["--name product-docs --workspace-id ws-xxx", "--name sub --parent-id cate-xxx"],
+  validate(flags) {
+    if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // categoryType fixed to UNSTRUCTURED (the only valid value for knowledge-base creation today)
+    const body = {
+      categoryName: flags.name,
+      categoryType: "UNSTRUCTURED",
+      ...(flags.parentId ? { parentCategoryId: flags.parentId } : {}),
+      ...(flags.collectionId ? { connectorId: flags.collectionId } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.addCategory);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAddCategoryResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const categoryId = response.data?.categoryId;
+    if (settings.quiet) {
+      emitBare(categoryId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(`created: ${categoryId ?? "-"}  (${flags.name})`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/category-delete.ts b/packages/commands/src/commands/knowledge/category-delete.ts
new file mode 100644
index 00000000..58c0c28b
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/category-delete.ts
@@ -0,0 +1,65 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagConnectorResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const CATEGORY_DELETE_FLAGS = {
+  categoryId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Category ID to delete",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Delete a data-center category",
+  auth: "apiKey",
+  usageArgs: "--category-id <id> [flags]",
+  flags: CATEGORY_DELETE_FLAGS,
+  notes: [
+    "Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.",
+  ],
+  exampleArgs: ["--category-id cate-xxx --workspace-id ws-xxx", "--category-id cate-xxx --yes"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = { categoryId: flags.categoryId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.deleteCategory);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    await confirmDangerousAction(
+      `Delete category ${flags.categoryId}\nThis cannot be undone.`,
+      flags.yes ?? false,
+    );
+
+    const response = await ctx.client.requestJson<
+      RagConnectorResponse<Record<string, unknown> | undefined>
+    >({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`deleted: ${flags.categoryId}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/category-list.ts b/packages/commands/src/commands/knowledge/category-list.ts
new file mode 100644
index 00000000..b1480bea
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/category-list.ts
@@ -0,0 +1,98 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagListCategoryResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, truncateLine, WORKSPACE_FLAG } from "./shared.ts";
+
+const CATEGORY_LIST_FLAGS = {
+  collectionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Filter by exact collection ID",
+  },
+  parentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "List sub-categories of this exact parent category",
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Filter by category name (exact match, unlike the knowledge base list)",
+  },
+  nextToken: {
+    type: "string",
+    valueHint: "<token>",
+    description: "Cursor for the next page (from previous output)",
+  },
+  maxResult: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Items per page (default: 20)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List data-center categories",
+  auth: "apiKey",
+  usageArgs: "[flags]",
+  flags: CATEGORY_LIST_FLAGS,
+  notes: [
+    "Categories marked [default] are where files land when no category is specified.",
+    "Pagination is cursor-based: reuse the printed next token to continue.",
+  ],
+  exampleArgs: ["--workspace-id ws-xxx", "--name my-category", "--next-token <token>"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // type fixed to UNSTRUCTURED, not exposed as a flag (the only valid value today); note: maxResult is singular
+    const body = {
+      type: "UNSTRUCTURED",
+      ...(flags.collectionId ? { connectorId: flags.collectionId } : {}),
+      ...(flags.parentId ? { parentId: flags.parentId } : {}),
+      ...(flags.name ? { categoryName: flags.name } : {}),
+      ...(flags.nextToken ? { nextToken: flags.nextToken } : {}),
+      ...(flags.maxResult !== undefined ? { maxResult: flags.maxResult } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.listCategory);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagListCategoryResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const categories = response.data?.categoryList ?? [];
+    if (settings.quiet) {
+      for (const category of categories) emitBare(category.categoryId ?? "");
+      return;
+    }
+    if (format === "text") {
+      if (categories.length === 0) {
+        emitBare("No categories found.");
+      } else {
+        for (const category of categories) {
+          const defaultMark = category.isDefault ? "  [default]" : "";
+          emitBare(truncateLine(`${category.categoryId}  ${category.categoryName}${defaultMark}`));
+        }
+      }
+      const nextToken = response.data?.nextToken;
+      if (nextToken) emitBare(`next: --next-token ${nextToken}`);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/chat.ts b/packages/commands/src/commands/knowledge/chat.ts
index 9e0d2559..3e5e03c1 100644
--- a/packages/commands/src/commands/knowledge/chat.ts
+++ b/packages/commands/src/commands/knowledge/chat.ts
@@ -13,6 +13,7 @@ import {
   type KnowledgeChatStreamChunk,
 } from "bailian-cli-core";
 import { ansi, emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
 
 const CHAT_FLAGS = {
   message: {
@@ -27,11 +28,15 @@ const CHAT_FLAGS = {
     description: "Q&A service ID (find in console knowledge Q&A page)",
     required: true,
   },
-  // 知识库走 workspace 专属域名,--workspace-id 属命令自有 flag(console 凭证域不适用)。
-  workspaceId: {
+  // Knowledge APIs use a workspace-specific host, so --workspace-id is a per-command
+  // flag here (the console credential scope does not apply).
+  ...WORKSPACE_FLAG,
+  // Named to avoid the runtime-reserved global --version flag
+  agentVersion: {
     type: "string",
-    valueHint: "<id>",
-    description: "Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)",
+    valueHint: "<version>",
+    description:
+      "Service version to call: beta (draft for debugging) or a published number; default is the latest published version",
   },
   image: {
     type: "array",
@@ -146,6 +151,7 @@ export default defineCommand({
     "Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.",
     "`--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.",
     'Multi-turn: use --message "user:..." and --message "assistant:..." to pass conversation history.',
+    "`--agent-version beta` calls the draft config for debugging before it is deployed.",
   ],
   exampleArgs: [
     '--message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx',
@@ -168,14 +174,7 @@ export default defineCommand({
       messages = [{ role: "user", content: "" }];
     }
 
-    const workspaceId = flags.workspaceId || settings.workspaceId;
-    if (!workspaceId) {
-      throw new BailianError(
-        "Workspace ID is required.",
-        ExitCode.USAGE,
-        `Pass --workspace-id, set BAILIAN_WORKSPACE_ID env, or configure: ${ctx.identity.binName} config set workspace_id <id>`,
-      );
-    }
+    const workspaceId = resolveWorkspaceId(ctx);
 
     const format = detectOutputFormat(settings.output);
     // API only supports SSE; streamOutput controls whether to print tokens in real-time
@@ -199,6 +198,9 @@ export default defineCommand({
       parameters: {
         agent_options: {
           agent_id: flags.agentId,
+          // Omitted flag → field not sent (default behavior unchanged); the value is
+          // not validated — the set of versions is server-side state
+          ...(flags.agentVersion ? { agent_version: flags.agentVersion } : {}),
         },
       },
       stream: true,
diff --git a/packages/commands/src/commands/knowledge/chunk-add.ts b/packages/commands/src/commands/knowledge/chunk-add.ts
new file mode 100644
index 00000000..de4eb505
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/chunk-add.ts
@@ -0,0 +1,165 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+  type RagMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+import { readUtf8TextFile } from "./upload-support.ts";
+
+const CHUNK_ADD_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  docId: {
+    type: "string",
+    valueHint: "<id>",
+    description:
+      "Owning document ID from the doc list command; required in practice for all knowledge base types",
+  },
+  content: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Chunk body text, up to 6000 chars (document-type); alternative to --content-file",
+  },
+  contentFile: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Read chunk body from a UTF-8 plain text file (.md/.txt etc.)",
+  },
+  title: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Chunk title, up to 50 chars (document-type)",
+  },
+  imageUrl: {
+    type: "array",
+    valueHint: "<url>",
+    description: "Chunk image URL (repeatable, up to 10; document-type)",
+  },
+  field: {
+    type: "array",
+    valueHint: "<key=value>",
+    description:
+      "Arbitrary field entry (repeatable) for table/image knowledge bases where keys are Excel column headers; mutually exclusive with content/title/image flags",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Parse --field key=value: split on the first =, value may contain = */
+export function parseFieldEntries(entries: string[]): Record<string, string> {
+  const field: Record<string, string> = {};
+  for (const entry of entries) {
+    const separatorIndex = entry.indexOf("=");
+    if (separatorIndex <= 0) {
+      throw new BailianError(`--field must be key=value, got: ${entry}`, ExitCode.USAGE);
+    }
+    field[entry.slice(0, separatorIndex)] = entry.slice(separatorIndex + 1);
+  }
+  return field;
+}
+
+export default defineCommand({
+  description: "Add a chunk directly to a knowledge base",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> (--content <text> | --field <k=v>) [flags]",
+  flags: CHUNK_ADD_FLAGS,
+  notes: [
+    "Document / table / image knowledge bases are supported; audio-video ones are not.",
+    "--doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.",
+    "Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.",
+    "The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.",
+    "The response carries no chunk id; list chunks afterwards to find the new one.",
+    "For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.",
+  ],
+  exampleArgs: [
+    '--index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx',
+    "--index-id idx-xxx --field 列A=v1 --field 列B=v2",
+  ],
+  validate(flags) {
+    const hasConvenience =
+      flags.content !== undefined ||
+      flags.contentFile !== undefined ||
+      flags.title !== undefined ||
+      !!flags.imageUrl?.length;
+    const hasField = !!flags.field?.length;
+    if (hasConvenience && hasField) {
+      return "--field is mutually exclusive with --content/--content-file/--title/--image-url";
+    }
+    if (!hasConvenience && !hasField) {
+      return "Provide chunk content via --content/--content-file or --field entries";
+    }
+    if (flags.content !== undefined && flags.contentFile !== undefined) {
+      return "Use either --content or --content-file, not both";
+    }
+    if (flags.content !== undefined && flags.content.length > 6000) {
+      return "--content must be at most 6000 characters";
+    }
+    if (flags.title !== undefined && flags.title.length > 50) {
+      return "--title must be at most 50 characters";
+    }
+    if (flags.imageUrl !== undefined && flags.imageUrl.length > 10) {
+      return "--image-url accepts at most 10 entries";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // dry-run also reads the file and parses --field (rehearsal semantics)
+    let field: Record<string, unknown>;
+    if (flags.field?.length) {
+      field = parseFieldEntries(flags.field);
+    } else {
+      const content =
+        flags.contentFile !== undefined
+          ? readUtf8TextFile(flags.contentFile, "--content")
+          : flags.content;
+      if (typeof content === "string" && content.length > 6000) {
+        throw new BailianError("Chunk content must be at most 6000 characters", ExitCode.USAGE);
+      }
+      field = {
+        ...(content !== undefined ? { content } : {}),
+        ...(flags.title !== undefined ? { title: flags.title } : {}),
+        ...(flags.imageUrl?.length ? { image_urls: flags.imageUrl } : {}),
+      };
+    }
+
+    const body = {
+      pipelineId: flags.indexId,
+      ...(flags.docId ? { dataId: flags.docId } : {}),
+      field,
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.chunkCreate);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    // The response carries no chunk_id — quiet mode exits 0 silently on success
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`chunk created (pipeline: ${flags.indexId})`);
+      emitBare("List chunks to find the new chunk id.");
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/chunk-delete.ts b/packages/commands/src/commands/knowledge/chunk-delete.ts
new file mode 100644
index 00000000..36f70aea
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/chunk-delete.ts
@@ -0,0 +1,105 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  type FlagsDef,
+  type RagMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const CHUNK_DELETE_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  chunkId: {
+    type: "array",
+    valueHint: "<id>",
+    description: "Chunk ID to delete (repeatable; batches of 10 are sent automatically)",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** The server caps each request at 10 chunk ids — the client batches automatically (bulk delete is where the CLI beats the console) */
+export function splitIntoBatches(chunkIds: string[], batchSize = 10): string[][] {
+  const batches: string[][] = [];
+  for (let batchStart = 0; batchStart < chunkIds.length; batchStart += batchSize) {
+    batches.push(chunkIds.slice(batchStart, batchStart + batchSize));
+  }
+  return batches;
+}
+
+export default defineCommand({
+  description: "Delete chunks from a knowledge base (irreversible)",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> --chunk-id <id> [flags]",
+  flags: CHUNK_DELETE_FLAGS,
+  notes: ["Accepts at most 10 chunk ids per call; larger sets are batched automatically."],
+  exampleArgs: [
+    "--index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx",
+    "--index-id idx-xxx --chunk-id chunk-a --yes",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const batches = splitIntoBatches(flags.chunkId);
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.chunkDelete);
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          endpoint,
+          batches: batches.map((batchIds) => ({
+            request: { pipelineId: flags.indexId, chunkIds: batchIds },
+          })),
+        },
+        format,
+      );
+      return;
+    }
+
+    await confirmDangerousAction(
+      `Delete ${flags.chunkId.length} chunk(s) from knowledge base ${flags.indexId} in ${batches.length} batch(es).\nChunks are permanently removed. This cannot be undone.`,
+      flags.yes ?? false,
+    );
+
+    // Sequential batches; any batch failure aborts, listing already-deleted batches in the error
+    let deletedCount = 0;
+    for (const batchIds of batches) {
+      try {
+        await ctx.client.requestJson<RagMutationResponse>({
+          path: endpoint,
+          method: "POST",
+          body: { pipelineId: flags.indexId, chunkIds: batchIds },
+        });
+        deletedCount += batchIds.length;
+      } catch (error) {
+        if (deletedCount > 0 && error instanceof BailianError && !error.hint) {
+          throw new BailianError(
+            error.message,
+            error.exitCode,
+            `${deletedCount} chunk(s) in earlier batches were already deleted.`,
+            { cause: error, api: error.api, rawResponse: error.rawResponse },
+          );
+        }
+        throw error;
+      }
+    }
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`deleted: ${deletedCount} chunk(s) in ${batches.length} batch(es)`);
+      return;
+    }
+    emitResult({ deleted_count: deletedCount, batches: batches.length }, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/chunk-list.ts b/packages/commands/src/commands/knowledge/chunk-list.ts
new file mode 100644
index 00000000..13f949de
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/chunk-list.ts
@@ -0,0 +1,101 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagChunkListResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, PAGE_FLAGS, WORKSPACE_FLAG } from "./shared.ts";
+
+const CHUNK_LIST_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  docId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Only show chunks belonging to this document",
+  },
+  ...PAGE_FLAGS,
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List chunks in a knowledge base with content and status",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: CHUNK_LIST_FLAGS,
+  notes: [
+    "Use metadata._id as the chunk id and metadata.doc_id as the document id in chunk update/delete commands.",
+    "Page size defaults to 20 (server default), max 100.",
+  ],
+  exampleArgs: [
+    "--index-id idx-xxx --workspace-id ws-xxx",
+    "--index-id idx-xxx --doc-id file-xxx --page-size 50",
+  ],
+  validate(flags) {
+    if (flags.pageSize !== undefined && (flags.pageSize < 1 || flags.pageSize > 100)) {
+      return "--page-size must be between 1 and 100";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Gotcha: this endpoint's pagination keys are pageNum/pageSize (camelCase, in the body)
+    const body = {
+      indexId: flags.indexId,
+      pageNum: flags.pageNumber ?? 1,
+      pageSize: flags.pageSize ?? 20,
+      ...(flags.docId ? { docId: flags.docId } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.chunkList);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagChunkListResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const nodes = response.data?.nodes ?? [];
+    if (settings.quiet) {
+      // chunk ids only, for piping into chunk update/delete
+      for (const node of nodes) emitBare(node.metadata?._id ?? "");
+      return;
+    }
+    if (format === "text") {
+      if (nodes.length === 0) {
+        emitBare("No chunks found.");
+      } else {
+        for (const node of nodes) {
+          const metadata = node.metadata ?? {};
+          const statusPart = metadata._chunk_status_message
+            ? `  status: ${metadata._chunk_status_message}`
+            : "";
+          const excludedPart =
+            metadata.is_displayed_chunk_content === false ? "  [excluded from retrieval]" : "";
+          emitBare(
+            `[chunk] ${metadata._id ?? "?"}  (doc: ${metadata.doc_name ?? "?"}, doc_id: ${metadata.doc_id ?? "?"})${statusPart}${excludedPart}`,
+          );
+          const contentText = metadata.content ?? node.text ?? "";
+          emitBare(`  ${contentText.length > 200 ? `${contentText.slice(0, 200)}…` : contentText}`);
+        }
+      }
+      emitBare(`total: ${response.data?.total ?? nodes.length}`);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/chunk-update.ts b/packages/commands/src/commands/knowledge/chunk-update.ts
new file mode 100644
index 00000000..c14e87ca
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/chunk-update.ts
@@ -0,0 +1,175 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type Client,
+  type FlagsDef,
+  type RagChunkListResponse,
+  type RagMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+import { readUtf8TextFile } from "./upload-support.ts";
+
+const CHUNK_UPDATE_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  chunkId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Chunk ID (metadata._id from the chunk list output)",
+    required: true,
+  },
+  docId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Document ID owning the chunk (metadata.doc_id from the chunk list output)",
+    required: true,
+  },
+  content: {
+    type: "string",
+    valueHint: "<text>",
+    description: "New chunk content, 10-6000 chars; alternative to --content-file",
+  },
+  contentFile: {
+    type: "string",
+    valueHint: "<path>",
+    description: "Read new content from a UTF-8 plain text file (.md/.txt etc.)",
+  },
+  title: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Chunk title, 0-50 chars (empty string clears it; omit to keep unchanged)",
+  },
+  exclude: { type: "switch", description: "Exclude this chunk from retrieval" },
+  include: { type: "switch", description: "Include this chunk in retrieval (default)" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** When only toggling include/exclude, read back the current content first (the API requires content — hide that quirk from users) */
+async function fetchChunkContent(
+  client: Client,
+  workspaceId: string,
+  indexId: string,
+  chunkId: string,
+  docId: string,
+): Promise<string> {
+  const maxPages = 10;
+  for (let pageNum = 1; pageNum <= maxPages; pageNum++) {
+    const response = await client.requestJson<RagChunkListResponse>({
+      path: ragEndpoint(workspaceId, RAG_PATHS.chunkList),
+      method: "POST",
+      body: { indexId, docId, pageNum, pageSize: 100 },
+    });
+    const nodes = response.data?.nodes ?? [];
+    const match = nodes.find((node) => node.metadata?._id === chunkId);
+    const matchContent = match?.metadata?.content ?? match?.text;
+    if (typeof matchContent === "string") return matchContent;
+    if (nodes.length < 100) break;
+  }
+  throw new BailianError(
+    `Chunk not found: ${chunkId}`,
+    ExitCode.GENERAL,
+    "Check the chunk id via the chunk list command.",
+  );
+}
+
+export default defineCommand({
+  description: "Update chunk content or toggle its retrieval visibility",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> --chunk-id <id> --doc-id <id> [flags]",
+  flags: CHUNK_UPDATE_FLAGS,
+  notes: [
+    "Content must be 10-6000 characters and within the knowledge base's max chunk size.",
+    "--content-file expects a UTF-8 plain text file; document formats (.docx/.pdf) are not parsed here.",
+    "Toggling --exclude/--include without new content re-submits the existing content automatically.",
+  ],
+  exampleArgs: [
+    '--index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text"',
+    "--index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude",
+  ],
+  validate(flags) {
+    if (flags.content !== undefined && flags.contentFile !== undefined) {
+      return "Use either --content or --content-file, not both";
+    }
+    if (flags.exclude && flags.include) return "--exclude and --include are mutually exclusive";
+    const hasContent = flags.content !== undefined || flags.contentFile !== undefined;
+    if (!hasContent && !flags.exclude && !flags.include && flags.title === undefined) {
+      return "Nothing to update — pass --content/--content-file, --title, --exclude or --include";
+    }
+    // Content lower-bound is enforced here (not deferred to run) so dry-run and
+    // missing-flag diagnostics surface the same error as the live request.
+    if (flags.content !== undefined && (flags.content.length < 10 || flags.content.length > 6000)) {
+      return "--content must be 10-6000 characters";
+    }
+    if (flags.title !== undefined && flags.title.length > 50) {
+      return "--title must be at most 50 characters";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // dry-run also reads the file and validates (rehearsal semantics); the read-back
+    // request is only made outside dry-run and when no new content is given
+    let content =
+      flags.contentFile !== undefined
+        ? readUtf8TextFile(flags.contentFile, "--content")
+        : flags.content;
+    if (content !== undefined && (content.length < 10 || content.length > 6000)) {
+      throw new BailianError("Chunk content must be 10-6000 characters", ExitCode.USAGE);
+    }
+
+    if (content === undefined) {
+      if (settings.dryRun) {
+        content = "<current-content (fetched at run time)>";
+      } else {
+        content = await fetchChunkContent(
+          ctx.client,
+          workspaceId,
+          flags.indexId,
+          flags.chunkId,
+          flags.docId,
+        );
+      }
+    }
+
+    const body = {
+      pipelineId: flags.indexId,
+      chunkId: flags.chunkId,
+      dataId: flags.docId,
+      content,
+      // Without exclude/include the chunk stays retrievable (safe default)
+      isDisplayedChunkContent: !flags.exclude,
+      ...(flags.title !== undefined ? { title: flags.title } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.chunkUpdate);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`updated: ${flags.chunkId}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/collection-create.ts b/packages/commands/src/commands/knowledge/collection-create.ts
new file mode 100644
index 00000000..67fa53f3
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/collection-create.ts
@@ -0,0 +1,113 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAddConnectorResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const COLLECTION_CREATE_FLAGS = {
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Collection name",
+    required: true,
+  },
+  description: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Collection description (required by the server)",
+    required: true,
+  },
+  storeType: {
+    type: "string",
+    valueHint: "<type>",
+    description: "Storage: platform (managed) or custom (your own OSS bucket)",
+  },
+  ossRegion: {
+    type: "string",
+    valueHint: "<id>",
+    description: "OSS region id (required with --store-type custom)",
+  },
+  ossBucket: {
+    type: "string",
+    valueHint: "<name>",
+    description: "OSS bucket name (required with --store-type custom)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a FILE data collection",
+  auth: "apiKey",
+  usageArgs: "--name <text> --description <text> [flags]",
+  flags: COLLECTION_CREATE_FLAGS,
+  notes: [
+    "Store type defaults to platform (managed storage); custom uses your authorized OSS bucket.",
+    "Custom buckets must carry the bucket tag bailian-connector-access=ReadAndWrite (Bailian's tag-based access control); without it the server rejects creation with a misleading 'setBucketCORS failed' error.",
+    "There is no collection delete API — create collections deliberately.",
+  ],
+  exampleArgs: [
+    "--name my-collection --description 'team docs' --workspace-id ws-xxx",
+    "--name oss-coll --description 'own bucket' --store-type custom --oss-region cn-beijing --oss-bucket my-bucket",
+  ],
+  validate(flags) {
+    // Server rejects names longer than 20 characters ("Connector name is longer than 20")
+    if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters";
+    const storeType = flags.storeType ?? "platform";
+    if (storeType !== "platform" && storeType !== "custom") {
+      return "--store-type must be platform or custom";
+    }
+    if (storeType === "custom" && (!flags.ossRegion || !flags.ossBucket)) {
+      return "--store-type custom requires --oss-region and --oss-bucket";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const storeType = (flags.storeType ?? "platform").toUpperCase();
+    // The server contract still uses connector* fields; only the CLI-facing term is collection.
+    // CUSTOM fields are regionId/bucketName per api/connector/add-connector.md (live-verified;
+    // the earlier ossRegionId/ossBucket naming was an implementation error, rejected with InvalidParameter).
+    const body = {
+      connectorType: "FILE",
+      connectorName: flags.name,
+      description: flags.description,
+      fileConnectorConfig: {
+        storeType,
+        ...(storeType === "CUSTOM"
+          ? { regionId: flags.ossRegion, bucketName: flags.ossBucket }
+          : {}),
+      },
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.addConnector);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAddConnectorResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const collectionId = response.data?.connectorId;
+    if (settings.quiet) {
+      emitBare(collectionId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(`created: ${collectionId ?? "-"}  (${flags.name}, ${storeType})`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/collection-get.ts b/packages/commands/src/commands/knowledge/collection-get.ts
new file mode 100644
index 00000000..62be71f3
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/collection-get.ts
@@ -0,0 +1,75 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagGetConnectorResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const COLLECTION_GET_FLAGS = {
+  collectionId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Collection ID; alternative to --name",
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Collection name; alternative to --collection-id",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Show data collection details",
+  auth: "apiKey",
+  usageArgs: "(--collection-id <id> | --name <text>) [flags]",
+  flags: COLLECTION_GET_FLAGS,
+  exampleArgs: ["--collection-id conn-xxx --workspace-id ws-xxx", "--name my-collection"],
+  validate(flags) {
+    if (!flags.collectionId && !flags.name) return "Pass --collection-id or --name";
+    if (flags.collectionId && flags.name) return "Use either --collection-id or --name, not both";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // The server contract still uses connector* fields; only the CLI-facing term is collection
+    const body = {
+      ...(flags.collectionId ? { connectorId: flags.collectionId } : {}),
+      ...(flags.name ? { connectorName: flags.name } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.getConnector);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagGetConnectorResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const collection = response.data;
+    if (settings.quiet) {
+      emitBare(collection?.connectorId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(`id: ${collection?.connectorId ?? "-"}`);
+      emitBare(`name: ${collection?.connectorName ?? "-"}`);
+      emitBare(`description: ${collection?.description ?? "-"}`);
+      // getConnector does not return fileConnectorConfig (storeType/regionId/bucketName);
+      // these fields are only available on the create request body.
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-delete.ts b/packages/commands/src/commands/knowledge/doc-delete.ts
new file mode 100644
index 00000000..356399ae
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-delete.ts
@@ -0,0 +1,96 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagDeleteFileResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const DOC_DELETE_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  docId: {
+    type: "array",
+    valueHint: "<id>",
+    description: "Document ID to delete (repeatable)",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Confirmation summary: list all doc_ids up to 5, otherwise show the first 5 + total count */
+function buildDeleteSummary(indexId: string, docIds: string[]): string {
+  const listed =
+    docIds.length <= 5
+      ? docIds.join("\n  ")
+      : `${docIds.slice(0, 5).join("\n  ")}\n  ... (${docIds.length} documents total)`;
+  return `Delete ${docIds.length} document(s) from knowledge base ${indexId}:\n  ${listed}\nDocuments and all their chunks are permanently removed from the index. This cannot be undone.`;
+}
+
+export default defineCommand({
+  description: "Delete documents and their chunks from a knowledge base",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> --doc-id <id> [flags]",
+  flags: DOC_DELETE_FLAGS,
+  notes: [
+    "Removes documents from the knowledge base index only; the source files remain in the data center.",
+    "Use the doc_id from `knowledge doc list --quiet`, not the fileId from `knowledge doc upload`. For documents created via `knowledge create --doc-id`, the doc_id equals the fileId; for documents imported via `knowledge doc upload --index-id`, the doc_id may include a workspace suffix.",
+    "Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.",
+    "The output lists the ids actually deleted.",
+  ],
+  exampleArgs: [
+    "--index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx",
+    "--index-id idx-xxx --doc-id file-a --doc-id file-b --yes",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // snake_case: body { index_id, doc_ids }
+    const body = { index_id: flags.indexId, doc_ids: flags.docId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.indexDeleteFile);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    await confirmDangerousAction(
+      buildDeleteSummary(flags.indexId, flags.docId),
+      flags.yes ?? false,
+    );
+
+    const response = await ctx.client.requestJson<RagDeleteFileResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    // Output follows the server's data.deleted list
+    const deleted = response.data?.deleted ?? [];
+    if (settings.quiet) {
+      for (const docId of deleted) emitBare(docId);
+      return;
+    }
+    if (format === "text") {
+      emitBare(`deleted: ${deleted.length} document(s)`);
+      for (const docId of deleted) emitBare(`  ${docId}`);
+      if (deleted.length !== flags.docId.length) {
+        process.stderr.write(
+          `Warning: requested ${flags.docId.length} deletion(s) but the server reported ${deleted.length}.\n`,
+        );
+      }
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-import-oss.ts b/packages/commands/src/commands/knowledge/doc-import-oss.ts
new file mode 100644
index 00000000..9db0468c
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-import-oss.ts
@@ -0,0 +1,117 @@
+import { basename } from "node:path";
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagOssImportResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const DOC_IMPORT_OSS_FLAGS = {
+  bucket: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Authorized OSS bucket name",
+    required: true,
+  },
+  region: {
+    type: "string",
+    valueHint: "<id>",
+    description: "OSS region id (e.g. cn-beijing)",
+    required: true,
+  },
+  ossKey: {
+    type: "array",
+    valueHint: "<key>",
+    description: "OSS object key to import (repeatable, 1-10 per call)",
+    required: true,
+  },
+  categoryId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Target data-center category (default: the default category)",
+  },
+  tag: {
+    type: "array",
+    valueHint: "<text>",
+    description: "File tag applied to every imported file (repeatable, up to 10)",
+  },
+  overwrite: {
+    type: "switch",
+    description: "Overwrite files previously imported from the same OSS keys",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Batch import files from an authorized OSS bucket into the data center",
+  auth: "apiKey",
+  usageArgs: "--bucket <name> --region <id> --oss-key <key> [flags]",
+  flags: DOC_IMPORT_OSS_FLAGS,
+  notes: [
+    "The bucket must be authorized to the platform service role beforehand; permission errors from the server are passed through with a pointer to check AliyunServiceRoleForBailian in the RAM console.",
+    "File names are derived from the OSS key basename.",
+    "--overwrite replaces the previously imported file and issues a NEW fileId (the old one becomes invalid) — verified live.",
+  ],
+  exampleArgs: [
+    "--bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx",
+    "--bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite",
+  ],
+  validate(flags) {
+    if (flags.ossKey.length > 10) return "--oss-key accepts at most 10 entries per call";
+    if (flags.tag !== undefined && flags.tag.length > 10) {
+      return "--tag accepts at most 10 entries";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // categoryType fixed to UNSTRUCTURED; parser not exposed as a flag (defaults to AUTO_SELECT)
+    const body = {
+      categoryId: flags.categoryId ?? "default",
+      categoryType: "UNSTRUCTURED",
+      ossBucket: flags.bucket,
+      ossRegionId: flags.region,
+      fileDetails: flags.ossKey.map((ossKey) => ({ fileName: basename(ossKey), ossKey })),
+      ...(flags.tag?.length ? { tags: flags.tag } : {}),
+      ...(flags.overwrite ? { overWriteFileByOssKey: true } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.addFilesFromAuthorizedOss);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagOssImportResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    // Live-verified shape: results come back as addFileResultList (the docs' flat
+    // fileIds field is not returned); per-file status is SUCCESS on success
+    const results = response.data?.addFileResultList ?? [];
+    const fileIds = results
+      .map((result) => result.fileId)
+      .filter((fileId): fileId is string => !!fileId);
+    if (settings.quiet) {
+      for (const fileId of fileIds) emitBare(fileId);
+      return;
+    }
+    if (format === "text") {
+      emitBare(`imported: ${fileIds.length} file(s)`);
+      for (const result of results) {
+        emitBare(`  ${result.fileId ?? "-"}  ${result.status ?? "-"}  ${result.ossKey ?? ""}`);
+      }
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-list.ts b/packages/commands/src/commands/knowledge/doc-list.ts
new file mode 100644
index 00000000..8fe5398e
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-list.ts
@@ -0,0 +1,83 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagIndexFilesResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, ansi } from "bailian-cli-runtime";
+import { resolveWorkspaceId, truncateLine, PAGE_FLAGS, WORKSPACE_FLAG } from "./shared.ts";
+
+const DOC_LIST_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  ...PAGE_FLAGS,
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List documents in a knowledge base with parse/index status",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: DOC_LIST_FLAGS,
+  notes: [
+    "Documents with status FAILED are highlighted in text mode — use the import job status command to inspect failures.",
+    "Page size defaults to 10 (server default), max 100.",
+  ],
+  exampleArgs: ["--index-id idx-xxx --workspace-id ws-xxx", "--index-id idx-xxx --page-size 100"],
+  validate(flags) {
+    if (flags.pageSize !== undefined && (flags.pageSize < 1 || flags.pageSize > 100)) {
+      return "--page-size must be between 1 and 100";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Gotcha: this endpoint's page parameter is page_num (not page_number)
+    const url = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexFiles));
+    url.searchParams.set("index_id", flags.indexId);
+    url.searchParams.set("page_num", String(flags.pageNumber ?? 1));
+    url.searchParams.set("page_size", String(flags.pageSize ?? 10));
+    const endpoint = url.toString();
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: null }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagIndexFilesResponse>({
+      path: endpoint,
+      method: "GET",
+    });
+
+    const rows = response.data?.rows ?? [];
+    if (settings.quiet) {
+      for (const row of rows) emitBare(row.doc_id ?? "");
+      return;
+    }
+    if (format === "text") {
+      const styles = ansi(process.stdout);
+      if (rows.length === 0) {
+        emitBare("No documents found.");
+      } else {
+        for (const row of rows) {
+          const line = truncateLine(
+            [row.doc_id, row.status, row.doc_name, row.doc_type ?? "-", row.size ?? "-"].join("  "),
+          );
+          emitBare(row.status === "FAILED" ? styles.red(line) : line);
+        }
+      }
+      emitBare(`total: ${response.data?.total_count ?? rows.length}`);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-status.ts b/packages/commands/src/commands/knowledge/doc-status.ts
new file mode 100644
index 00000000..c48fa7e3
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-status.ts
@@ -0,0 +1,124 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+  type RagIndexJobStatusResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, ansi } from "bailian-cli-runtime";
+import {
+  resolveWorkspaceId,
+  PAGE_FLAGS,
+  WORKSPACE_FLAG,
+  failedImportDocs,
+  importJobFailureMessage,
+  pollImportJob,
+} from "./shared.ts";
+
+const DOC_STATUS_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  jobId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Import job ID (ingestionId returned by import commands)",
+    required: true,
+  },
+  ...PAGE_FLAGS,
+  wait: { type: "switch", description: "Poll until the job reaches a terminal state" },
+  pollInterval: {
+    type: "number",
+    valueHint: "<seconds>",
+    description: "Polling interval when waiting (default: 5)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+function printStatus(response: RagIndexJobStatusResponse): void {
+  const styles = ansi(process.stdout);
+  emitBare(`status: ${response.data?.ingestion_status ?? "UNKNOWN"}`);
+  for (const doc of response.data?.rows ?? []) {
+    const docState = doc.code ?? doc.status ?? "?";
+    const line = `  ${doc.doc_id ?? "?"}  ${docState}  ${doc.doc_name ?? ""}`;
+    emitBare(docState.includes("FAILED") ? styles.red(line) : line);
+  }
+}
+
+export default defineCommand({
+  description: "Check knowledge base import job status",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> --job-id <id> [flags]",
+  flags: DOC_STATUS_FLAGS,
+  notes: [
+    "Both --index-id and --job-id are required (passing only one returns SystemError).",
+    "If you see a SystemError, the job may not exist — check the ingestion id in the document list output.",
+    "Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.",
+  ],
+  exampleArgs: [
+    "--index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx",
+    "--index-id idx-xxx --job-id job-xxx --wait --poll-interval 10",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Both required flags are enforced by the parser up front; parameters go in
+    // the query string (they are ignored in the body)
+    const url = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexJobStatus));
+    url.searchParams.set("index_id", flags.indexId);
+    url.searchParams.set("job_id", flags.jobId);
+    if (flags.pageNumber !== undefined) {
+      url.searchParams.set("page_number", String(flags.pageNumber));
+    }
+    if (flags.pageSize !== undefined) {
+      url.searchParams.set("page_size", String(flags.pageSize));
+    }
+    const endpoint = url.toString();
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: null }, format);
+      return;
+    }
+
+    let response: RagIndexJobStatusResponse;
+    if (flags.wait) {
+      // Reuse the shared polling (timeout → TIMEOUT(5)); failure detection happens
+      // uniformly after return, based on per-document status
+      response = await pollImportJob(ctx.client, settings, {
+        statusUrl: endpoint,
+        intervalSec: flags.pollInterval ?? 5,
+      });
+    } else {
+      response = await ctx.client.requestJson<RagIndexJobStatusResponse>({
+        path: endpoint,
+        method: "GET",
+      });
+    }
+
+    // Any per-document failure means a non-zero exit; the server message is passed through verbatim
+    if (failedImportDocs(response).length > 0) {
+      throw new BailianError(
+        importJobFailureMessage(response, "Import job reported document failures."),
+        ExitCode.GENERAL,
+      );
+    }
+
+    if (settings.quiet) {
+      emitBare(response.data?.ingestion_status ?? "UNKNOWN");
+      return;
+    }
+    if (format === "text") {
+      printStatus(response);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-tag.ts b/packages/commands/src/commands/knowledge/doc-tag.ts
new file mode 100644
index 00000000..55a31076
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-tag.ts
@@ -0,0 +1,88 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagBatchUpdateTagResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const DOC_TAG_FLAGS = {
+  docId: {
+    type: "array",
+    valueHint: "<id>",
+    description: "Data-center file ID to tag (repeatable, 1-20 per call)",
+    required: true,
+  },
+  tag: {
+    type: "array",
+    valueHint: "<text>",
+    description: "Tag applied to every --doc-id (repeatable, each up to 32 chars)",
+    required: true,
+  },
+  mode: {
+    type: "string",
+    valueHint: "<mode>",
+    description: "Update mode: append (default) or overwrite",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Batch update tags on data-center files",
+  auth: "apiKey",
+  usageArgs: "--doc-id <id> --tag <text> [flags]",
+  flags: DOC_TAG_FLAGS,
+  notes: [
+    "The same tag set is applied to every --doc-id; run the command multiple times for different tag sets.",
+    "Server limits: up to 100 tags per file, total tag length up to 700 chars, tag up to 32 chars.",
+  ],
+  exampleArgs: [
+    "--doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx",
+    "--doc-id file-a --doc-id file-b --tag final --mode overwrite",
+  ],
+  validate(flags) {
+    if (flags.docId.length > 20) return "--doc-id accepts at most 20 ids per call";
+    if (flags.mode !== undefined && flags.mode !== "append" && flags.mode !== "overwrite") {
+      return "--mode must be append or overwrite";
+    }
+    // Hard limits stated by the API contract: each tag ≤32 chars; ≤100 tags per file; total length ≤700
+    if (flags.tag.length > 100) return "At most 100 tags per file";
+    const overlongTag = flags.tag.find((tag) => tag.length > 32);
+    if (overlongTag) return `Tag exceeds 32 characters: ${overlongTag}`;
+    const totalLength = flags.tag.reduce((sum, tag) => sum + tag.length, 0);
+    if (totalLength > 700) return "Total tag length exceeds 700 characters";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = {
+      fileInfos: flags.docId.map((fileId) => ({ fileId, tags: flags.tag })),
+      updateMode: (flags.mode ?? "append").toUpperCase(),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.batchUpdateFileTag);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagBatchUpdateTagResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`tagged: ${flags.docId.length} file(s) with [${flags.tag.join(", ")}]`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/doc-upload.ts b/packages/commands/src/commands/knowledge/doc-upload.ts
new file mode 100644
index 00000000..b81e1ca6
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/doc-upload.ts
@@ -0,0 +1,322 @@
+// Orchestration command: local file → data center → (optional) import into a knowledge base.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+  type RagUploadLeaseResponse,
+  type RagAddFileResponse,
+  type RagJobCreateResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import {
+  resolveWorkspaceId,
+  WORKSPACE_FLAG,
+  failedImportDocs,
+  importJobFailureMessage,
+  importJobStatus,
+  importJobStatusUrl,
+  pollImportJob,
+  withPartialSuccessHint,
+} from "./shared.ts";
+import { checkUploadFile, expandUploadPaths } from "./upload-support.ts";
+
+const DOC_UPLOAD_FLAGS = {
+  file: {
+    type: "array",
+    valueHint: "<path>",
+    description:
+      "Local file or directory path (repeatable). Directories are scanned recursively; unsupported formats are skipped",
+    required: true,
+  },
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Import into this knowledge base after registration (one job for all files)",
+  },
+  categoryId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Target data-center category; defaults to the workspace default category",
+  },
+  tag: {
+    type: "array",
+    valueHint: "<text>",
+    description: "File tag (repeatable), applied to every uploaded file",
+  },
+  wait: {
+    type: "switch",
+    description: "Poll the import job to a terminal state (needs --index-id)",
+  },
+  pollInterval: {
+    type: "number",
+    valueHint: "<seconds>",
+    description: "Polling interval when waiting (default: 5)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+interface UploadedFile {
+  path: string;
+  fileId: string;
+}
+
+export default defineCommand({
+  description:
+    "Upload local files or directories to the data center and optionally import into a knowledge base",
+  auth: "apiKey",
+  usageArgs: "--file <path> [flags]",
+  flags: DOC_UPLOAD_FLAGS,
+  notes: [
+    "Pipeline: apply upload lease → PUT to OSS → register file → (with --index-id) create import job.",
+    "Without --category-id the workspace default category is resolved automatically.",
+    "Directories are scanned recursively; node_modules, .git, and similar are skipped automatically.",
+    "Multiple files are processed sequentially; on failure, already-registered file ids are listed in the error hint.",
+  ],
+  exampleArgs: [
+    "--file ./a.md --workspace-id ws-xxx",
+    "--file ./a.md --file ./b.pdf --index-id idx-xxx --wait",
+    "--file ./docs/ --workspace-id ws-xxx",
+    "--file ./docs/ --dry-run --verbose",
+  ],
+  validate(flags) {
+    if (flags.wait && !flags.indexId) return "--wait requires --index-id";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Expand directories into individual file paths; unsupported extensions are
+    // collected into `skipped` rather than throwing (directory-scan semantics)
+    const { files: expandedFiles, skipped } = expandUploadPaths(flags.file);
+    if (expandedFiles.length === 0) {
+      throw new BailianError(
+        "No supported files found",
+        ExitCode.USAGE,
+        `Supported formats: .pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif`,
+      );
+    }
+
+    // Local pre-flight validation also runs in dry-run (rehearsal semantics: surface
+    // file problems early); exceeding a soft limit only warns
+    const checkedFiles = expandedFiles.map((filePath) => {
+      const checked = checkUploadFile(filePath);
+      if (checked.warning) process.stderr.write(`Warning: ${checked.warning}\n`);
+      return { filePath, sizeBytes: checked.sizeBytes };
+    });
+
+    if (settings.dryRun) {
+      // dry-run does not read file contents (md5 shown as a placeholder)
+      const categoryPlaceholder = flags.categoryId ?? "default";
+      const steps = checkedFiles.flatMap((checkedFile) => [
+        {
+          step: "applyFileUploadLease",
+          endpoint: ragEndpoint(workspaceId, RAG_PATHS.applyFileUploadLease),
+          request: {
+            category: categoryPlaceholder,
+            fileName: basename(checkedFile.filePath),
+            sizeBytes: String(checkedFile.sizeBytes), // gotcha: must be a string
+            contentMd5: "<md5-base64>",
+          } as unknown,
+        },
+        {
+          step: "ossPut",
+          endpoint: "<lease.param.url>",
+          request: { method: "PUT", headers: "<lease.param.headers>" } as unknown,
+        },
+        {
+          step: "addFile",
+          endpoint: ragEndpoint(workspaceId, RAG_PATHS.addFile),
+          request: {
+            leaseId: "<leaseId>",
+            category: categoryPlaceholder,
+            parser: "AUTO_SELECT",
+            ...(flags.tag?.length ? { tags: flags.tag } : {}),
+          } as unknown,
+        },
+      ]);
+      if (flags.indexId) {
+        steps.push({
+          step: "createImportJob",
+          endpoint: ragEndpoint(workspaceId, RAG_PATHS.indexJobCreate),
+          request: {
+            indexId: flags.indexId,
+            // Live-verified: the field name is docIds (not documentIds as in the
+            // public docs); omitting sourceType would import the entire data center.
+            sourceType: "DATA_CENTER_FILE",
+            docIds: ["<fileId>"],
+          } as unknown,
+        });
+      }
+      emitResult({ steps, skipped }, format);
+      return;
+    }
+
+    // Default category: the literal "default" is accepted by lease/addFile
+    // (verified against the live API), so no listCategory resolution is needed
+    const categoryId = flags.categoryId ?? "default";
+
+    // Multiple files run steps 1-3 sequentially (no concurrency in this version,
+    // to avoid OSS rate-limit complexity)
+    const uploaded: UploadedFile[] = [];
+    for (const checkedFile of checkedFiles) {
+      try {
+        const fileBuffer = readFileSync(checkedFile.filePath);
+        const contentMd5 = createHash("md5").update(fileBuffer).digest("base64");
+
+        // 1) Apply for an upload lease (gotcha: the category parameter is named
+        //    category, not categoryId; sizeBytes must be a string)
+        const lease = await ctx.client.requestJson<RagUploadLeaseResponse>({
+          path: ragEndpoint(workspaceId, RAG_PATHS.applyFileUploadLease),
+          method: "POST",
+          body: {
+            category: categoryId,
+            fileName: basename(checkedFile.filePath),
+            sizeBytes: String(checkedFile.sizeBytes),
+            contentMd5,
+          },
+        });
+        const leaseId = lease.data?.leaseId;
+        const leaseParam = lease.data?.param;
+        if (!leaseId || !leaseParam?.url) {
+          throw new BailianError(
+            `Upload lease response missing leaseId/url for ${checkedFile.filePath}`,
+            ExitCode.GENERAL,
+          );
+        }
+
+        // 2) OSS upload: goes to the OSS host, not the DashScope gateway — native fetch without a Bearer header
+        let ossResponse: Response;
+        try {
+          ossResponse = await fetch(leaseParam.url, {
+            method: leaseParam.method ?? "PUT",
+            headers: leaseParam.headers,
+            body: fileBuffer,
+          });
+        } catch (error) {
+          const causeCode = (error as { cause?: { code?: string } }).cause?.code;
+          throw new BailianError(
+            `OSS upload failed for ${basename(checkedFile.filePath)}`,
+            ExitCode.NETWORK,
+            causeCode ? `Network error (${causeCode}).` : undefined,
+            { cause: error },
+          );
+        }
+        if (!ossResponse.ok) {
+          const ossBody = await ossResponse.text().catch(() => "");
+          throw new BailianError(
+            `OSS upload rejected (HTTP ${ossResponse.status}) for ${basename(checkedFile.filePath)}${ossBody ? `: ${ossBody.slice(0, 300)}` : ""}`,
+            ExitCode.GENERAL,
+          );
+        }
+
+        // 3) Register the file
+        const added = await ctx.client.requestJson<RagAddFileResponse>({
+          path: ragEndpoint(workspaceId, RAG_PATHS.addFile),
+          method: "POST",
+          body: {
+            leaseId,
+            category: categoryId,
+            parser: "AUTO_SELECT",
+            ...(flags.tag?.length ? { tags: flags.tag } : {}),
+          },
+        });
+        const fileId = added.data?.fileId;
+        if (!fileId) {
+          throw new BailianError(
+            `addFile response missing fileId for ${checkedFile.filePath}`,
+            ExitCode.GENERAL,
+          );
+        }
+        uploaded.push({ path: checkedFile.filePath, fileId });
+      } catch (error) {
+        // Partial-failure semantics: abort with an error, listing already-registered
+        // fileIds in the hint (re-uploading is cheap and idempotent)
+        if (uploaded.length > 0) {
+          throw withPartialSuccessHint(
+            error,
+            `Already registered: ${uploaded.map((item) => item.fileId).join(", ")}`,
+          );
+        }
+        throw error;
+      }
+    }
+
+    // 4) Optional import (merged into a single job after all files are registered)
+    let ingestionId: string | undefined;
+    let finalStatus: string | undefined;
+    if (flags.indexId) {
+      const job = await ctx.client.requestJson<RagJobCreateResponse>({
+        path: ragEndpoint(workspaceId, RAG_PATHS.indexJobCreate),
+        method: "POST",
+        body: {
+          indexId: flags.indexId,
+          // Live-verified: the field name is docIds (not documentIds as in the
+          // public docs); omitting sourceType would import the entire data center.
+          sourceType: "DATA_CENTER_FILE",
+          docIds: uploaded.map((item) => item.fileId),
+        },
+      });
+      ingestionId = job.data?.ingestionId;
+      if (flags.wait && ingestionId) {
+        const statusResponse = await pollImportJob(ctx.client, settings, {
+          statusUrl: importJobStatusUrl(workspaceId, flags.indexId, ingestionId).toString(),
+          intervalSec: flags.pollInterval ?? 5,
+        });
+        finalStatus = importJobStatus(statusResponse);
+        // Job finished but some documents failed to parse → non-zero exit, server message passed through verbatim
+        if (failedImportDocs(statusResponse).length > 0) {
+          throw new BailianError(
+            importJobFailureMessage(statusResponse, "Import job reported document failures."),
+            ExitCode.GENERAL,
+            `Registered file ids: ${uploaded.map((item) => item.fileId).join(", ")}`,
+          );
+        }
+      }
+    }
+
+    if (settings.quiet) {
+      for (const item of uploaded) emitBare(item.fileId);
+      return;
+    }
+    if (format === "text") {
+      for (const item of uploaded) {
+        emitBare(`${basename(item.path)}  ${item.fileId}  registered`);
+      }
+      if (ingestionId) emitBare(`job: ${ingestionId}`);
+      if (finalStatus) emitBare(`status: ${finalStatus}`);
+      // Summary line: always show counts; list skipped files only with --verbose
+      const summaryParts = [`Uploaded ${uploaded.length} file${uploaded.length !== 1 ? "s" : ""}`];
+      if (skipped.length > 0) {
+        summaryParts.push(`skipped ${skipped.length} unsupported`);
+      }
+      emitBare(`\n${summaryParts.join(", ")}.`);
+      if (settings.verbose && skipped.length > 0) {
+        emitBare("Skipped files:");
+        for (const skippedPath of skipped) {
+          emitBare(`  ${basename(skippedPath)}`);
+        }
+      }
+      return;
+    }
+    // An orchestration command has no single response to pass through — emit a custom stable shape
+    emitResult(
+      {
+        files: uploaded.map((item) => ({ path: item.path, fileId: item.fileId })),
+        skipped,
+        ...(flags.indexId ? { index_id: flags.indexId } : {}),
+        ...(ingestionId ? { ingestion_id: ingestionId } : {}),
+        ...(finalStatus ? { final_status: finalStatus } : {}),
+      },
+      format,
+    );
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/file-delete.ts b/packages/commands/src/commands/knowledge/file-delete.ts
new file mode 100644
index 00000000..d9986ddb
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/file-delete.ts
@@ -0,0 +1,88 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type Client,
+  type FlagsDef,
+  type RagConnectorResponse,
+  type RagDescribeFileResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const FILE_DELETE_FLAGS = {
+  fileId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Data-center file ID to delete",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Confirmation summary lookup (file name/size); failure degrades to id-only */
+async function buildDeleteSummary(
+  client: Client,
+  workspaceId: string,
+  fileId: string,
+): Promise<string> {
+  let infoPart = "";
+  try {
+    const detail = await client.requestJson<RagDescribeFileResponse>({
+      path: ragEndpoint(workspaceId, RAG_PATHS.describeFile),
+      method: "POST",
+      body: { fileId },
+    });
+    if (detail.data?.fileName) infoPart = `  name: ${detail.data.fileName}`;
+  } catch {
+    // Degrade gracefully: a failed lookup does not block confirmation
+  }
+  return `Delete data-center file ${fileId}${infoPart}\nPERMANENT: if the file is referenced by knowledge bases, their document indexes break too. This differs from removing a document from one knowledge base.`;
+}
+
+export default defineCommand({
+  description: "Permanently delete a file from the data center",
+  auth: "apiKey",
+  usageArgs: "--file-id <id> [flags]",
+  flags: FILE_DELETE_FLAGS,
+  notes: [
+    "Irreversible. If knowledge bases reference this file, their related document indexes become invalid.",
+    "To remove a document from a single knowledge base only, use the document delete command instead.",
+  ],
+  exampleArgs: ["--file-id file-xxx --workspace-id ws-xxx", "--file-id file-xxx --yes"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = { fileId: flags.fileId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.deleteFile);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const summary = flags.yes
+      ? ""
+      : await buildDeleteSummary(ctx.client, workspaceId, flags.fileId);
+    await confirmDangerousAction(summary, flags.yes ?? false);
+
+    const response = await ctx.client.requestJson<
+      RagConnectorResponse<Record<string, unknown> | undefined>
+    >({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`deleted: ${flags.fileId}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/file-get.ts b/packages/commands/src/commands/knowledge/file-get.ts
new file mode 100644
index 00000000..3ff414fc
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/file-get.ts
@@ -0,0 +1,67 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagDescribeFileResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const FILE_GET_FLAGS = {
+  fileId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Data-center file ID",
+    required: true,
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Show data-center file details (size, MD5, tags, timestamps)",
+  auth: "apiKey",
+  usageArgs: "--file-id <id> [flags]",
+  flags: FILE_GET_FLAGS,
+  exampleArgs: ["--file-id file-xxx --workspace-id ws-xxx"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = { fileId: flags.fileId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.describeFile);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagDescribeFileResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const file = response.data;
+    if (settings.quiet) {
+      emitBare(file?.fileId ?? "");
+      return;
+    }
+    if (format !== "text") {
+      emitResult(response, format);
+      return;
+    }
+    emitBare(`id: ${file?.fileId ?? "-"}`);
+    emitBare(`name: ${file?.fileName ?? "-"}`);
+    emitBare(`type: ${file?.fileType ?? "-"}`);
+    emitBare(`size: ${file?.sizeBytes ?? "-"}`);
+    emitBare(`status: ${file?.status ?? "-"}`);
+    emitBare(`parser: ${file?.parser ?? "-"}`);
+    emitBare(`category: ${file?.category ?? "-"}`);
+    emitBare(`uploaded: ${file?.uploadTime ?? "-"}`);
+    const tags = Array.isArray(file?.tags) ? file.tags.join(", ") : (file?.tags ?? "-");
+    emitBare(`tags: ${tags || "-"}`);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/file-list.ts b/packages/commands/src/commands/knowledge/file-list.ts
new file mode 100644
index 00000000..ac7fe902
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/file-list.ts
@@ -0,0 +1,104 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagListFileResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, truncateLine, WORKSPACE_FLAG } from "./shared.ts";
+
+const FILE_LIST_FLAGS = {
+  categoryId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Category to list (find ids via the category list command); exact match",
+    required: true,
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Filter by exact file name without its extension (a.md → pass a)",
+  },
+  fileId: {
+    type: "array",
+    valueHint: "<id>",
+    description: "Filter by exact file ID (repeatable)",
+  },
+  nextToken: {
+    type: "string",
+    valueHint: "<token>",
+    description: "Cursor for the next page (from previous output)",
+  },
+  maxResult: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Items per page",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List files in a data-center category",
+  auth: "apiKey",
+  usageArgs: "--category-id <id> [flags]",
+  flags: FILE_LIST_FLAGS,
+  notes: [
+    "A real category id is required — the default value is not resolved here. Find the id via the category list command.",
+    "--name matches the exact file name without its extension (for a.md pass a); partial keywords return no results.",
+    "Pagination is cursor-based: reuse the printed next token to continue.",
+  ],
+  exampleArgs: [
+    "--category-id cate-xxx --workspace-id ws-xxx",
+    "--category-id cate-xxx --name report",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = {
+      categoryId: flags.categoryId,
+      ...(flags.name ? { fileName: flags.name } : {}),
+      ...(flags.fileId?.length ? { fileIds: flags.fileId } : {}),
+      ...(flags.nextToken ? { nextToken: flags.nextToken } : {}),
+      ...(flags.maxResult !== undefined ? { maxResult: flags.maxResult } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.listFile);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagListFileResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const files = response.data?.fileList ?? [];
+    if (settings.quiet) {
+      for (const file of files) emitBare(file.fileId ?? "");
+      return;
+    }
+    if (format === "text") {
+      if (files.length === 0) {
+        emitBare("No files found.");
+      } else {
+        for (const file of files) {
+          emitBare(
+            truncateLine(
+              [file.fileId, file.status ?? "-", file.fileName, file.sizeBytes ?? "-"].join("  "),
+            ),
+          );
+        }
+      }
+      const nextToken = response.data?.nextToken;
+      if (nextToken) emitBare(`next: --next-token ${nextToken}`);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-create.ts b/packages/commands/src/commands/knowledge/kb-create.ts
new file mode 100644
index 00000000..474f1152
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-create.ts
@@ -0,0 +1,166 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+  type RagCreateIndexV2Response,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import {
+  resolveWorkspaceId,
+  WORKSPACE_FLAG,
+  failedImportDocs,
+  importJobFailureMessage,
+  importJobStatus,
+  importJobStatusUrl,
+  pollImportJob,
+} from "./shared.ts";
+
+const KB_CREATE_FLAGS = {
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Knowledge base name (1-20 chars, unique in workspace)",
+    required: true,
+  },
+  docId: {
+    type: "array",
+    valueHint: "<id>",
+    description:
+      "Data-center file id to import (repeatable); mutually exclusive with --category-id",
+  },
+  categoryId: {
+    type: "array",
+    valueHint: "<id>",
+    description:
+      "Import every file under this category (repeatable); mutually exclusive with --doc-id",
+  },
+  embeddingModel: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Embedding model name (default: text-embedding-v4)",
+  },
+  chunkSize: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Chunk size in characters (default: 600, recommended 300-800)",
+  },
+  wait: { type: "switch", description: "Poll the initial import job to a terminal state" },
+  pollInterval: {
+    type: "number",
+    valueHint: "<seconds>",
+    description: "Polling interval when waiting (default: 5)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** sourceType/docIds/categoryIds derivation, centralized for unit testing (gotcha: the parameter is docIds, not fileIds) */
+export function buildDataSourceFields(flags: { docId?: string[]; categoryId?: string[] }): {
+  sourceType: string;
+  docIds?: string[];
+  categoryIds?: string[];
+  dataSources: Array<{ sourceType: string }>;
+} {
+  if (flags.docId?.length) {
+    return {
+      sourceType: "DATA_CENTER_FILE",
+      docIds: flags.docId,
+      dataSources: [{ sourceType: "DATA_CENTER_FILE" }],
+    };
+  }
+  return {
+    sourceType: "DATA_CENTER_CATEGORY",
+    categoryIds: flags.categoryId,
+    dataSources: [{ sourceType: "DATA_CENTER_CATEGORY" }],
+  };
+}
+
+export default defineCommand({
+  description: "Create a knowledge base and import data-center files or categories",
+  auth: "apiKey",
+  usageArgs: "--name <text> (--doc-id <id> | --category-id <id>) [flags]",
+  flags: KB_CREATE_FLAGS,
+  notes: [
+    "Structure/sink types are fixed to the default document knowledge base (unstructured, BUILT_IN storage).",
+    "Returns the knowledge base id (pipelineId) and the initial import job id (ingestionId).",
+    "Use the import job status command (or --wait) to track the initial import.",
+  ],
+  exampleArgs: [
+    "--name demo --doc-id file-xxx --workspace-id ws-xxx",
+    "--name demo --category-id cate-xxx --wait",
+  ],
+  validate(flags) {
+    if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters";
+    const hasDocIds = !!flags.docId?.length;
+    const hasCategoryIds = !!flags.categoryId?.length;
+    if (hasDocIds && hasCategoryIds) return "Use either --doc-id or --category-id, not both";
+    if (!hasDocIds && !hasCategoryIds)
+      return "Provide --doc-id or --category-id as the data source";
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Fixed values, not exposed as flags in this version: structureType unstructured, sinkType BUILT_IN.
+    // Note: the public docs' example uses sinkType DEFAULT, but BUILT_IN is what works against the live API.
+    const body = {
+      name: flags.name,
+      structureType: "unstructured",
+      sinkType: "BUILT_IN",
+      embeddingModelName: flags.embeddingModel ?? "text-embedding-v4",
+      chunkSize: flags.chunkSize ?? 600,
+      ...buildDataSourceFields(flags),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.indexCreateV2);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagCreateIndexV2Response>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+    const pipelineId = response.data?.pipelineId;
+    const ingestionId = response.data?.ingestionId;
+
+    let finalStatus: string | undefined;
+    if (flags.wait && pipelineId && ingestionId) {
+      const statusResponse = await pollImportJob(ctx.client, settings, {
+        statusUrl: importJobStatusUrl(workspaceId, pipelineId, ingestionId).toString(),
+        intervalSec: flags.pollInterval ?? 5,
+      });
+      finalStatus = importJobStatus(statusResponse);
+      // Job finished but some documents failed to parse → non-zero exit, server message
+      // passed through verbatim (the knowledge base was created; its id goes in the hint)
+      if (failedImportDocs(statusResponse).length > 0) {
+        throw new BailianError(
+          importJobFailureMessage(statusResponse, "Initial import reported document failures."),
+          ExitCode.GENERAL,
+          `Knowledge base created: ${pipelineId}`,
+          { api: { requestId: statusResponse.request_id } },
+        );
+      }
+    }
+
+    if (settings.quiet) {
+      emitBare(pipelineId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(`index_id: ${pipelineId ?? "-"}`);
+      if (ingestionId) emitBare(`ingestion_id: ${ingestionId}`);
+      if (finalStatus) emitBare(`status: ${finalStatus}`);
+      emitBare("Next: check the import job status, then search against this knowledge base.");
+      return;
+    }
+    emitResult(finalStatus ? { ...response, final_status: finalStatus } : response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-delete.ts b/packages/commands/src/commands/knowledge/kb-delete.ts
new file mode 100644
index 00000000..2f9ddb5e
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-delete.ts
@@ -0,0 +1,98 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagIndexFilesResponse,
+  type RagMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+import { fetchIndexDetail } from "./kb-info.ts";
+
+const KB_DELETE_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Confirmation summary lookup: name + document count; any lookup failure degrades to id-only (never blocks deletion) */
+async function buildDeleteSummary(
+  ctx: { client: Parameters<typeof fetchIndexDetail>[0] },
+  workspaceId: string,
+  indexId: string,
+): Promise<string> {
+  let namePart = "";
+  let docCountPart = "";
+  try {
+    const detail = await fetchIndexDetail(ctx.client, workspaceId, indexId);
+    namePart = `  name: ${detail.name}`;
+  } catch {
+    // Degrade gracefully: a missing name does not block confirmation
+  }
+  try {
+    const filesUrl = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexFiles));
+    filesUrl.searchParams.set("index_id", indexId);
+    filesUrl.searchParams.set("page_num", "1");
+    filesUrl.searchParams.set("page_size", "1");
+    const files = await ctx.client.requestJson<RagIndexFilesResponse>({
+      path: filesUrl.toString(),
+      method: "GET",
+    });
+    const totalCount = files.data?.total_count;
+    if (typeof totalCount === "number") docCountPart = `  documents: ${totalCount}`;
+  } catch {
+    // Same graceful degradation as above
+  }
+  return `Delete knowledge base ${indexId}${namePart}${docCountPart}\nThis permanently removes the knowledge base with all documents and chunks. It cannot be undone.`;
+}
+
+export default defineCommand({
+  description: "Delete a knowledge base with all its documents and chunks",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: KB_DELETE_FLAGS,
+  notes: [
+    "Irreversible — the knowledge base and all indexed content are permanently removed.",
+    "Files in the data center are not affected; only the knowledge base index is deleted.",
+  ],
+  exampleArgs: ["--index-id idx-xxx --workspace-id ws-xxx", "--index-id idx-xxx --yes"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // This endpoint is back to snake_case: body { index_id }
+    const body = { index_id: flags.indexId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.indexDelete);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const summary = flags.yes
+      ? "" // --yes bypasses the prompt, so skip the summary lookups
+      : await buildDeleteSummary(ctx, workspaceId, flags.indexId);
+    await confirmDangerousAction(summary, flags.yes ?? false);
+
+    const response = await ctx.client.requestJson<RagMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`deleted: ${flags.indexId}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-info.ts b/packages/commands/src/commands/knowledge/kb-info.ts
new file mode 100644
index 00000000..cbb1dc1b
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-info.ts
@@ -0,0 +1,123 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type Client,
+  type FlagsDef,
+  type RagIndexListResponse,
+  type RagIndexRow,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const KB_INFO_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+function indexDetailUrl(workspaceId: string, indexId: string): string {
+  const url = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexList));
+  url.searchParams.set("pipeline_id", indexId);
+  url.searchParams.set("page_number", "1");
+  url.searchParams.set("page_size", "1");
+  return url.toString();
+}
+
+/**
+ * The index/list API now supports pipeline_id filtering, so a single
+ * request suffices instead of paginating. Reused by kb delete for its
+ * confirmation summary.
+ */
+export async function fetchIndexDetail(
+  client: Client,
+  workspaceId: string,
+  indexId: string,
+): Promise<RagIndexRow> {
+  const response = await client.requestJson<RagIndexListResponse>({
+    path: indexDetailUrl(workspaceId, indexId),
+    method: "GET",
+  });
+  const row = response.data?.rows?.[0];
+  if (!row) {
+    throw new BailianError(
+      `Knowledge base not found: ${indexId}`,
+      ExitCode.GENERAL,
+      "Check the id — list knowledge bases in this workspace to verify it.",
+    );
+  }
+  return row;
+}
+
+function formatField(label: string, value: string | number | boolean | null | undefined): string {
+  return `  ${label}: ${value ?? "-"}`;
+}
+
+export default defineCommand({
+  description: "Show knowledge base configuration details",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: KB_INFO_FLAGS,
+  notes: ["Indexing settings are immutable; changing them requires recreating the knowledge base."],
+  exampleArgs: ["--index-id idx-xxx --workspace-id ws-xxx"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          endpoint: indexDetailUrl(workspaceId, flags.indexId),
+          request: null,
+        },
+        format,
+      );
+      return;
+    }
+
+    const row = await fetchIndexDetail(ctx.client, workspaceId, flags.indexId);
+
+    if (settings.quiet) {
+      emitBare(row.id ?? "");
+      return;
+    }
+    if (format !== "text") {
+      emitResult(row, format);
+      return;
+    }
+
+    // Grouped by diagnostic concern; the immutable annotation on Indexing tells
+    // users which settings require recreating the knowledge base
+    emitBare("Basic:");
+    emitBare(formatField("id", row.id));
+    emitBare(formatField("name", row.name));
+    emitBare(formatField("description", row.description));
+    emitBare(formatField("dataType", row.dataType));
+    emitBare("Indexing:   [immutable — recreate required to change]");
+    emitBare(formatField("embeddingModelName", row.embeddingModelName));
+    emitBare(formatField("embeddingDimension", row.embeddingDimension));
+    emitBare(formatField("chunkSize", row.chunkSize));
+    emitBare(formatField("overlapSize", row.overlapSize));
+    emitBare(formatField("chunkMode", row.chunkMode));
+    emitBare(formatField("separator", row.separator));
+    emitBare("Retrieval:");
+    emitBare(formatField("rerankModelName", row.rerankModelName));
+    emitBare(formatField("rerankMinScore", row.rerankMinScore));
+    emitBare(formatField("rerankTopN", row.rerankTopN));
+    emitBare(formatField("rerankMode", row.rerankMode));
+    emitBare(formatField("enableRewrite", row.enableRewrite));
+    emitBare(formatField("denseSimilarityTopK", row.denseSimilarityTopK));
+    emitBare(formatField("sparseSimilarityTopK", row.sparseSimilarityTopK));
+    emitBare("Data:");
+    emitBare(formatField("sourceType", row.sourceType));
+    emitBare(formatField("connectorId", row.connectorId));
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-list.ts b/packages/commands/src/commands/knowledge/kb-list.ts
new file mode 100644
index 00000000..8e322dfd
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-list.ts
@@ -0,0 +1,92 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagIndexListResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, truncateLine, PAGE_FLAGS, WORKSPACE_FLAG } from "./shared.ts";
+
+const KB_LIST_FLAGS = {
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Filter by knowledge base name (fuzzy match, 1-20 chars)",
+  },
+  ...PAGE_FLAGS,
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "List knowledge bases in the workspace",
+  auth: "apiKey",
+  usageArgs: "[flags]",
+  flags: KB_LIST_FLAGS,
+  notes: [
+    "Auth: uses DashScope API Key (Bearer token).",
+    "`--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or config workspace_id.",
+    "Use the returned id as --index-id in knowledge base / document management commands.",
+  ],
+  exampleArgs: ["--workspace-id ws-xxx", "--name demo --page-number 2 --page-size 50"],
+  validate(flags) {
+    if (flags.name !== undefined && (flags.name.length < 1 || flags.name.length > 20)) {
+      return "--name must be 1-20 characters";
+    }
+    if (flags.pageSize !== undefined && (flags.pageSize < 1 || flags.pageSize > 100)) {
+      return "--page-size must be between 1 and 100";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Pagination and filter parameters must go in the query string — the server ignores them in the body
+    const url = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexList));
+    if (flags.name) url.searchParams.set("pipeline_name", flags.name);
+    url.searchParams.set("page_number", String(flags.pageNumber ?? 1));
+    url.searchParams.set("page_size", String(flags.pageSize ?? 20));
+    const endpoint = url.toString();
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: null }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagIndexListResponse>({
+      path: endpoint,
+      method: "GET",
+    });
+
+    const rows = response.data?.rows ?? [];
+    if (settings.quiet) {
+      for (const row of rows) emitBare(row.id);
+      return;
+    }
+    if (format === "text") {
+      if (rows.length === 0) {
+        emitBare("No knowledge bases found.");
+      } else {
+        for (const row of rows) {
+          emitBare(
+            truncateLine(
+              [
+                row.id,
+                row.name,
+                row.embeddingModelName ?? "-",
+                row.chunkSize ?? "-",
+                row.description ?? "",
+              ].join("  "),
+            ),
+          );
+        }
+      }
+      emitBare(`total: ${response.data?.total ?? rows.length}`);
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-stats.ts b/packages/commands/src/commands/knowledge/kb-stats.ts
new file mode 100644
index 00000000..5bb13a61
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-stats.ts
@@ -0,0 +1,125 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type FlagsDef,
+  type RagMonitorResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const KB_STATS_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  start: {
+    type: "string",
+    valueHint: "<time>",
+    description:
+      "Range start: Unix seconds or ISO date, must be in the past (default: 24 hours ago)",
+  },
+  end: {
+    type: "string",
+    valueHint: "<time>",
+    description: "Range end: Unix seconds or ISO date, must be in the past (default: now)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Normalize time input to a second-precision string (the API requires seconds as a string). Accepts Unix seconds or an ISO date. */
+export function toEpochSecondsString(input: string): string {
+  if (/^\d+$/.test(input)) {
+    // Digits-only input is treated as Unix seconds; 13-digit millisecond timestamps are reduced to seconds
+    return input.length >= 13 ? String(Math.floor(Number(input) / 1000)) : input;
+  }
+  // Non-numeric input must be a full ISO date (YYYY-MM-DD, optionally with a time
+  // part). Date.parse alone is too lenient — V8 silently reads truncated input
+  // like "2026-" as Jan 1st, which would query a misleading range.
+  const parsedMs = /^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(input) ? Date.parse(input) : Number.NaN;
+  if (Number.isNaN(parsedMs)) {
+    throw new BailianError(
+      `Invalid time value: ${input}`,
+      ExitCode.USAGE,
+      "Pass Unix seconds (e.g. 1780900000) or an ISO date (e.g. 2026-07-30T00:00:00Z).",
+    );
+  }
+  return String(Math.floor(parsedMs / 1000));
+}
+
+export default defineCommand({
+  description: "Show knowledge base storage and QPS monitoring data",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: KB_STATS_FLAGS,
+  notes: [
+    "Defaults to the last 24 hours when --start/--end are omitted.",
+    "Timestamps are normalized to epoch seconds as required by the server.",
+    "Future timestamps are rejected for --start and clamped to now for --end, since the monitor API only returns past data.",
+  ],
+  exampleArgs: [
+    "--index-id idx-xxx --workspace-id ws-xxx",
+    "--index-id idx-xxx --start 2026-07-30 --end 2026-07-31",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const startTimestamp = flags.start
+      ? toEpochSecondsString(flags.start)
+      : String(nowSeconds - 24 * 3600);
+    let endTimestamp = flags.end ? toEpochSecondsString(flags.end) : String(nowSeconds);
+
+    // The monitor API rejects future timestamps with a misleading
+    // "missing or invalid" error — validate here with a clear message.
+    if (Number(startTimestamp) > nowSeconds) {
+      throw new BailianError(
+        `Start time is in the future; the monitor API only accepts past or current timestamps.`,
+        ExitCode.USAGE,
+        "Use a start date/time at or before now, or omit --start to default to 24 hours ago.",
+      );
+    }
+    const clampedEnd = Number(endTimestamp) > nowSeconds;
+    if (clampedEnd) {
+      endTimestamp = String(nowSeconds);
+    }
+
+    const body = { indexId: flags.indexId, startTimestamp, endTimestamp };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.indexMonitor);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagMonitorResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (format !== "text") {
+      emitResult(response, format);
+      return;
+    }
+    if (clampedEnd) {
+      emitBare("note: end time was in the future, clamped to now.");
+    }
+    // Shape verified against the live API: the monitor fields are objects, not arrays
+    const storage = response.data?.storageMonitorData;
+    const qps = response.data?.qpsMonitorData;
+    emitBare(`plan: ${response.data?.pipelineCommercialType ?? "-"}`);
+    emitBare(
+      `storage: ${storage?.indexStorageUsage ?? "-"} / ${storage?.indexStorageLimit ?? "-"}`,
+    );
+    emitBare(`peak qps: ${qps?.peakQps ?? "-"}`);
+    emitBare(`qps windows: ${qps?.monitorData?.length ?? 0} data point(s)`);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/kb-update.ts b/packages/commands/src/commands/knowledge/kb-update.ts
new file mode 100644
index 00000000..c1cfc565
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/kb-update.ts
@@ -0,0 +1,100 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const KB_UPDATE_FLAGS = {
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Knowledge base ID",
+    required: true,
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "New knowledge base name (1-20 chars)",
+  },
+  description: {
+    type: "string",
+    valueHint: "<text>",
+    description: "New knowledge base description",
+  },
+  rerankMinScore: {
+    type: "number",
+    valueHint: "<score>",
+    description: "Rerank minimum score threshold, range 0-1 (chunks below are filtered)",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Update knowledge base name, description or rerank threshold",
+  auth: "apiKey",
+  usageArgs: "--index-id <id> [flags]",
+  flags: KB_UPDATE_FLAGS,
+  notes: [
+    "Indexing settings (embedding model, chunk size, etc.) are immutable — recreate the knowledge base to change them.",
+  ],
+  exampleArgs: [
+    "--index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx",
+    "--index-id idx-xxx --rerank-min-score 0.3",
+  ],
+  validate(flags) {
+    if (
+      flags.name === undefined &&
+      flags.description === undefined &&
+      flags.rerankMinScore === undefined
+    ) {
+      return "Nothing to update — pass --name, --description or --rerank-min-score";
+    }
+    if (flags.name !== undefined && (flags.name.length < 1 || flags.name.length > 20)) {
+      return "--name must be 1-20 characters";
+    }
+    if (
+      flags.rerankMinScore !== undefined &&
+      (flags.rerankMinScore < 0 || flags.rerankMinScore > 1)
+    ) {
+      return "--rerank-min-score must be between 0 and 1";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // Gotcha: this endpoint names the knowledge base ID parameter `id` (not index_id/indexId)
+    const body = {
+      id: flags.indexId,
+      ...(flags.name !== undefined ? { name: flags.name } : {}),
+      ...(flags.description !== undefined ? { description: flags.description } : {}),
+      ...(flags.rerankMinScore !== undefined ? { rerankMinScore: flags.rerankMinScore } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.indexUpdate);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`updated: ${flags.indexId}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/search.ts b/packages/commands/src/commands/knowledge/search.ts
index d23dd48b..ff2d92e6 100644
--- a/packages/commands/src/commands/knowledge/search.ts
+++ b/packages/commands/src/commands/knowledge/search.ts
@@ -2,13 +2,12 @@ import {
   defineCommand,
   knowledgeSearchEndpoint,
   detectOutputFormat,
-  BailianError,
-  ExitCode,
   type FlagsDef,
   type KnowledgeSearchRequest,
   type KnowledgeSearchResponse,
 } from "bailian-cli-core";
 import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
 
 const SEARCH_FLAGS = {
   query: {
@@ -23,23 +22,21 @@ const SEARCH_FLAGS = {
     description: "Retrieval service ID (find in console knowledge retrieval page)",
     required: true,
   },
-  // 知识库走 workspace 专属域名,--workspace-id 属命令自有 flag(console 凭证域不适用)。
-  workspaceId: {
+  // Knowledge APIs use a workspace-specific host, so --workspace-id is a per-command
+  // flag here (the console credential scope does not apply).
+  ...WORKSPACE_FLAG,
+  // Named to avoid the runtime-reserved global --version flag
+  agentVersion: {
     type: "string",
-    valueHint: "<id>",
-    description: "Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)",
+    valueHint: "<version>",
+    description:
+      "Service version to call: beta (draft for debugging) or a published number; default is the latest published version",
   },
   image: {
     type: "array",
     valueHint: "<url>",
     description: "Image URL for multimodal retrieval (repeatable)",
   },
-  queryHistory: {
-    type: "string",
-    valueHint: "<json>",
-    description:
-      'User conversation history JSON for context understanding and query rewriting. Format: \'[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is..."}]\'',
-  },
 } satisfies FlagsDef;
 
 export default defineCommand({
@@ -51,24 +48,16 @@ export default defineCommand({
     "Retrieval scope and strategy (multi-index weighting, routing, reranking, etc.) are driven by the agent_id service config. Only query and agent_id are required.",
     "Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.",
     "`--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.",
-    "`--query-history` passes prior conversation turns; the server rewrites the query based on context to improve retrieval relevance.",
+    "`--agent-version beta` calls the draft config for debugging before it is deployed.",
   ],
   exampleArgs: [
     '--query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx',
     '--api-key $DASHSCOPE_API_KEY --query "test search" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg',
-    '--query "How does it work" --agent-id aid-xxx --workspace-id ws-xxx --query-history \'[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is retrieval-augmented generation"}]\'',
   ],
   async run(ctx) {
     const { settings, flags } = ctx;
 
-    const workspaceId = flags.workspaceId || settings.workspaceId;
-    if (!workspaceId) {
-      throw new BailianError(
-        "Workspace ID is required.",
-        ExitCode.USAGE,
-        `Pass --workspace-id, set BAILIAN_WORKSPACE_ID env, or configure: ${ctx.identity.binName} config set workspace_id <id>`,
-      );
-    }
+    const workspaceId = resolveWorkspaceId(ctx);
 
     const format = detectOutputFormat(settings.output);
 
@@ -77,23 +66,14 @@ export default defineCommand({
       agent_id: flags.agentId,
     };
 
-    if (flags.image && flags.image.length > 0) {
-      body.images = flags.image;
+    // Omitted flag → field not sent (default behavior unchanged: latest published
+    // version); the value is not validated — the set of versions is server-side state
+    if (flags.agentVersion) {
+      body.agent_version = flags.agentVersion;
     }
 
-    // Parse query_history JSON for multi-turn context
-    if (flags.queryHistory) {
-      try {
-        body.query_history = JSON.parse(flags.queryHistory) as Array<{
-          role: "user" | "assistant";
-          content: string;
-        }>;
-      } catch {
-        throw new BailianError(
-          '--query-history must be valid JSON. Example: --query-history \'[{"role":"user","content":"What is RAG"}]\'',
-          ExitCode.USAGE,
-        );
-      }
+    if (flags.image && flags.image.length > 0) {
+      body.images = flags.image;
     }
 
     const url = knowledgeSearchEndpoint(workspaceId);
diff --git a/packages/commands/src/commands/knowledge/service-copy.ts b/packages/commands/src/commands/knowledge/service-copy.ts
new file mode 100644
index 00000000..ff1a05cd
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-copy.ts
@@ -0,0 +1,67 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAgentMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { agentMutationField, resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_COPY_FLAGS = {
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Source service (agent) ID to copy",
+    required: true,
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Copy a service into a new draft (name gets a copy_ prefix)",
+  auth: "apiKey",
+  usageArgs: "--agent-id <id> [flags]",
+  flags: SERVICE_COPY_FLAGS,
+  notes: [
+    "The copy starts as a beta draft; test it with --agent-version beta, then deploy to publish.",
+    "Requires the knowledge-base create permission in the workspace.",
+  ],
+  exampleArgs: ["--agent-id aid-xxx --workspace-id ws-xxx"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = { agent_id: flags.agentId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentCopy);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAgentMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const newAgentId = agentMutationField(response, "agent_id");
+    if (settings.quiet) {
+      emitBare(newAgentId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(
+        `new agent_id: ${newAgentId ?? "-"}  (name: ${agentMutationField(response, "agent_name") ?? "-"}, status: ${agentMutationField(response, "agent_status") ?? "draft"})`,
+      );
+      emitBare(
+        "Test the draft with --agent-version beta on search/chat, then deploy it to publish.",
+      );
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-create.ts b/packages/commands/src/commands/knowledge/service-create.ts
new file mode 100644
index 00000000..eae9d7d0
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-create.ts
@@ -0,0 +1,105 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAgentMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { agentMutationField, resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_CREATE_FLAGS = {
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Service name (up to 200 chars, unique per scene in the workspace)",
+    required: true,
+  },
+  scene: {
+    type: "string",
+    valueHint: "<scene>",
+    description: "Service scene: chat (Q&A) or search (retrieval)",
+    required: true,
+  },
+  description: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Service description (up to 1000 chars)",
+  },
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Bind this knowledge base; other settings use server defaults",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+export default defineCommand({
+  description: "Create a retrieval / Q&A service (initial status: draft, version: beta)",
+  auth: "apiKey",
+  usageArgs: "--name <text> --scene <chat|search> [flags]",
+  flags: SERVICE_CREATE_FLAGS,
+  notes: [
+    "Without an explicit configuration the server applies its default agent settings.",
+    "The draft (beta) version can be tested via --agent-version beta on search/chat before deploying.",
+    "Requires the knowledge-base create permission in the workspace.",
+  ],
+  exampleArgs: [
+    "--name my-qa --scene chat --workspace-id ws-xxx",
+    "--name my-search --scene search --index-id idx-xxx",
+  ],
+  validate(flags) {
+    if (flags.name.length > 200) return "--name must be at most 200 characters";
+    if (flags.scene !== "chat" && flags.scene !== "search") {
+      return "--scene must be chat or search";
+    }
+    if (flags.description !== undefined && flags.description.length > 1000) {
+      return "--description must be at most 1000 characters";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // agent_config is optional — omit to use server defaults; with --index-id build
+    // the minimal kb_search_configs (name/desc etc. are backfilled by the system from
+    // the knowledge base, so they are not sent)
+    const body = {
+      agent_name: flags.name,
+      agent_scene: flags.scene,
+      ...(flags.description ? { agent_desc: flags.description } : {}),
+      ...(flags.indexId ? { agent_config: { kb_search_configs: [{ id: flags.indexId }] } } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentCreate);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAgentMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const agentId = agentMutationField(response, "agent_id");
+    if (settings.quiet) {
+      emitBare(agentId ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(
+        `created: ${agentId ?? "-"}  (status: ${agentMutationField(response, "agent_status") ?? "draft"}, version: ${agentMutationField(response, "agent_version") ?? "beta"})`,
+      );
+      emitBare(
+        "Test the draft with --agent-version beta on search/chat, then deploy it to publish.",
+      );
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-delete.ts b/packages/commands/src/commands/knowledge/service-delete.ts
new file mode 100644
index 00000000..5725cef4
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-delete.ts
@@ -0,0 +1,98 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type Client,
+  type FlagsDef,
+  type RagAgentGetResponse,
+  type RagAgentMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { agentMutationField, resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_DELETE_FLAGS = {
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Service (agent) ID",
+    required: true,
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Confirmation summary lookup (name/status); failure degrades to id-only */
+async function buildDeleteSummary(
+  client: Client,
+  workspaceId: string,
+  agentId: string,
+): Promise<string> {
+  let infoPart = "";
+  let liveWarning = "";
+  try {
+    const detail = await client.requestJson<RagAgentGetResponse>({
+      path: ragEndpoint(workspaceId, RAG_PATHS.agentGet),
+      method: "POST",
+      body: { agent_id: agentId },
+    });
+    const name = detail.data?.agent_name;
+    const status = detail.data?.agent_status;
+    if (name) infoPart += `  name: ${name}`;
+    if (status) {
+      infoPart += `  status: ${status}`;
+      if (status === "deployed" || status === "edited") {
+        liveWarning = "\nWARNING: this service is LIVE — deleting it breaks existing callers.";
+      }
+    }
+  } catch {
+    // Degrade gracefully: a failed lookup does not block confirmation
+  }
+  return `Delete service ${agentId}${infoPart}${liveWarning}\nDeletion cannot be undone; the agent_id can no longer be used for search or chat calls.`;
+}
+
+export default defineCommand({
+  description: "Delete a retrieval / Q&A service (soft delete, idempotent)",
+  auth: "apiKey",
+  usageArgs: "--agent-id <id> [flags]",
+  flags: SERVICE_DELETE_FLAGS,
+  notes: [
+    "Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.",
+    "Idempotent — deleting an already-deleted service does not fail.",
+    "Requires the knowledge-base delete permission in the workspace.",
+  ],
+  exampleArgs: ["--agent-id aid-xxx --workspace-id ws-xxx", "--agent-id aid-xxx --yes"],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = { agent_id: flags.agentId };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentDelete);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const summary = flags.yes
+      ? ""
+      : await buildDeleteSummary(ctx.client, workspaceId, flags.agentId);
+    await confirmDangerousAction(summary, flags.yes ?? false);
+
+    const response = await ctx.client.requestJson<RagAgentMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(
+        `deleted: ${flags.agentId}  (status: ${agentMutationField(response, "agent_status") ?? "deleted"})`,
+      );
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-deploy.ts b/packages/commands/src/commands/knowledge/service-deploy.ts
new file mode 100644
index 00000000..99039977
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-deploy.ts
@@ -0,0 +1,112 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type Client,
+  type FlagsDef,
+  type RagAgentGetResponse,
+  type RagAgentMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare, confirmDangerousAction } from "bailian-cli-runtime";
+import { agentMutationField, resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_DEPLOY_FLAGS = {
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Service (agent) ID",
+    required: true,
+  },
+  versionDesc: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Description for the newly published version",
+  },
+  yes: { type: "switch", description: "Skip the confirmation prompt" },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+/** Confirmation summary lookup (name/status); warns that deploying an edited draft overwrites live behavior; failure degrades to id-only */
+async function buildDeploySummary(
+  client: Client,
+  workspaceId: string,
+  agentId: string,
+): Promise<string> {
+  let infoPart = "";
+  let editedWarning = "";
+  try {
+    const detail = await client.requestJson<RagAgentGetResponse>({
+      path: ragEndpoint(workspaceId, RAG_PATHS.agentGet),
+      method: "POST",
+      body: { agent_id: agentId },
+    });
+    const name = detail.data?.agent_name;
+    const status = detail.data?.agent_status;
+    if (name) infoPart += `  name: ${name}`;
+    if (status) {
+      infoPart += `  status: ${status}`;
+      if (status === "edited") {
+        editedWarning =
+          "\nWARNING: a published version is live — deploying replaces its behavior with the current draft.";
+      }
+    }
+  } catch {
+    // Degrade gracefully: a failed lookup does not block confirmation
+  }
+  return `Deploy service ${agentId}${infoPart}${editedWarning}\nPublishing changes what live callers get from this service.`;
+}
+
+export default defineCommand({
+  description: "Publish the beta draft of a service as a new version",
+  auth: "apiKey",
+  usageArgs: "--agent-id <id> [flags]",
+  flags: SERVICE_DEPLOY_FLAGS,
+  notes: [
+    "The version number auto-increments; status becomes deployed.",
+    "Publishing affects live callers — the confirmation prompt guards against accidents.",
+    "Requires the knowledge-base modify permission in the workspace.",
+  ],
+  exampleArgs: [
+    "--agent-id aid-xxx --workspace-id ws-xxx",
+    "--agent-id aid-xxx --version-desc 'tuned rerank params' --yes",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = {
+      agent_id: flags.agentId,
+      ...(flags.versionDesc ? { agent_version_desc: flags.versionDesc } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentDeploy);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const summary = flags.yes
+      ? ""
+      : await buildDeploySummary(ctx.client, workspaceId, flags.agentId);
+    await confirmDangerousAction(summary, flags.yes ?? false);
+
+    const response = await ctx.client.requestJson<RagAgentMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const newVersion = agentMutationField(response, "agent_version");
+    if (settings.quiet) {
+      emitBare(newVersion ?? "");
+      return;
+    }
+    if (format === "text") {
+      emitBare(`deployed: ${flags.agentId}  version ${newVersion ?? "-"}`);
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-get.ts b/packages/commands/src/commands/knowledge/service-get.ts
new file mode 100644
index 00000000..f8854245
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-get.ts
@@ -0,0 +1,98 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAgentDetail,
+  type RagAgentGetResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_GET_FLAGS = {
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Service (agent) ID",
+    required: true,
+  },
+  agentVersion: {
+    type: "string",
+    valueHint: "<version>",
+    description: "Specific version to inspect (beta or a published number); omit for all versions",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+function printDetail(detail: RagAgentDetail): void {
+  emitBare(`Version ${detail.agent_version ?? "?"}:`);
+  if (detail.agent_version_desc) emitBare(`  desc: ${detail.agent_version_desc}`);
+  if (detail.publish_time !== undefined) emitBare(`  published: ${detail.publish_time}`);
+  const config = detail.agent_config;
+  if (!config) return;
+  if (config.agent_policy) emitBare(`  policy: ${config.agent_policy}`);
+  if (config.agent_model) emitBare(`  model: ${config.agent_model}`);
+  if (config.temperature !== undefined) emitBare(`  temperature: ${config.temperature}`);
+  for (const kbConfig of config.kb_search_configs ?? []) {
+    const kbId = typeof kbConfig.id === "string" ? kbConfig.id : "?";
+    const kbName = typeof kbConfig.name === "string" ? `  (${kbConfig.name})` : "";
+    emitBare(`  kb: ${kbId}${kbName}`);
+  }
+}
+
+export default defineCommand({
+  description: "Show service (agent) details including per-version configuration",
+  auth: "apiKey",
+  usageArgs: "--agent-id <id> [flags]",
+  flags: SERVICE_GET_FLAGS,
+  notes: [
+    "Without --agent-version all versions are returned (beta draft plus published numbers).",
+    "The version value is passed through as-is; the valid set is server-side state.",
+  ],
+  exampleArgs: [
+    "--agent-id aid-xxx --workspace-id ws-xxx",
+    "--agent-id aid-xxx --agent-version beta",
+  ],
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const body = {
+      agent_id: flags.agentId,
+      ...(flags.agentVersion ? { agent_version: flags.agentVersion } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentGet);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAgentGetResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const data = response.data;
+    if (settings.quiet) {
+      emitBare(data?.agent_id ?? "");
+      return;
+    }
+    if (format !== "text") {
+      emitResult(response, format);
+      return;
+    }
+    emitBare("Basic:");
+    emitBare(`  id: ${data?.agent_id ?? "-"}`);
+    emitBare(`  name: ${data?.agent_name ?? "-"}`);
+    emitBare(`  desc: ${data?.agent_desc ?? "-"}`);
+    emitBare(`  scene: ${data?.agent_scene ?? "-"}`);
+    emitBare(`  status: ${data?.agent_status ?? "-"}`);
+    for (const detail of data?.agent_details ?? []) {
+      printDetail(detail);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-list.ts b/packages/commands/src/commands/knowledge/service-list.ts
new file mode 100644
index 00000000..e398a75a
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-list.ts
@@ -0,0 +1,134 @@
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  type FlagsDef,
+  type RagAgentListResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, truncateLine, PAGE_FLAGS, WORKSPACE_FLAG } from "./shared.ts";
+
+const SERVICE_LIST_FLAGS = {
+  scene: {
+    type: "string",
+    valueHint: "<scene>",
+    description: "Service scene: chat (Q&A) or search (retrieval). Required by the server",
+    required: true,
+  },
+  status: {
+    type: "string",
+    valueHint: "<status>",
+    description: "Filter by status: draft, deployed (includes edited) or deleted",
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Filter by service name (fuzzy match)",
+  },
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Filter by exact agent ID",
+  },
+  indexId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Filter by exact linked knowledge base (pipeline) ID",
+  },
+  ...PAGE_FLAGS,
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+const SCENES = ["chat", "search"];
+const STATUSES = ["draft", "deployed", "deleted"];
+
+export default defineCommand({
+  description: "List retrieval / Q&A services (agents) in the workspace",
+  auth: "apiKey",
+  usageArgs: "--scene <chat|search> [flags]",
+  flags: SERVICE_LIST_FLAGS,
+  notes: [
+    "A scene (chat or search) is required — run once per scene to see both.",
+    "Use the returned agent_id with the search or chat commands, or with service management commands.",
+  ],
+  exampleArgs: ["--scene chat --workspace-id ws-xxx", "--scene search --status deployed"],
+  validate(flags) {
+    if (!SCENES.includes(flags.scene)) return "--scene must be chat or search";
+    if (flags.status !== undefined && !STATUSES.includes(flags.status)) {
+      return "--status must be draft, deployed or deleted";
+    }
+    if (flags.pageSize !== undefined && (flags.pageSize < 1 || flags.pageSize > 100)) {
+      return "--page-size must be between 1 and 100";
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    // agent/list pagination goes in the body
+    const body = {
+      agent_scene: flags.scene,
+      ...(flags.status ? { agent_status: flags.status } : {}),
+      ...(flags.name ? { agent_name: flags.name } : {}),
+      ...(flags.agentId ? { agent_id: flags.agentId } : {}),
+      ...(flags.indexId ? { pipeline_id: flags.indexId } : {}),
+      page_number: flags.pageNumber ?? 1,
+      page_size: flags.pageSize ?? 10,
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentList);
+
+    if (settings.dryRun) {
+      emitResult({ endpoint, request: body }, format);
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAgentListResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    const rows = response.data?.rows ?? [];
+    if (settings.quiet) {
+      for (const row of rows) emitBare(row.agent_id ?? "");
+      return;
+    }
+    if (format === "text") {
+      if (rows.length === 0) {
+        emitBare("No services found.");
+      } else {
+        for (const row of rows) {
+          const kbNames = (row.pipeline_list ?? [])
+            .map((pipeline) => pipeline.pipeline_name)
+            .filter(Boolean)
+            .join(",");
+          emitBare(
+            truncateLine(
+              [
+                row.agent_id,
+                row.agent_status,
+                row.agent_version,
+                row.agent_name,
+                kbNames ? `(kb: ${kbNames})` : "",
+              ]
+                .filter(Boolean)
+                .join("  "),
+            ),
+          );
+        }
+      }
+      emitBare(`total: ${response.data?.total_count ?? rows.length}`);
+      // Connect finding an ID with using it (capability wording, no hardcoded product path)
+      emitBare(
+        flags.scene === "search"
+          ? "Use an agent_id above with the knowledge search command."
+          : "Use an agent_id above with the knowledge chat command.",
+      );
+    } else {
+      emitResult(response, format);
+    }
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/service-update.ts b/packages/commands/src/commands/knowledge/service-update.ts
new file mode 100644
index 00000000..f155b8ef
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/service-update.ts
@@ -0,0 +1,362 @@
+import { readFileSync } from "node:fs";
+import {
+  defineCommand,
+  ragEndpoint,
+  RAG_PATHS,
+  detectOutputFormat,
+  BailianError,
+  ExitCode,
+  type Client,
+  type FlagsDef,
+  type RagAgentConfig,
+  type RagAgentGetResponse,
+  type RagAgentMutationResponse,
+} from "bailian-cli-core";
+import { emitResult, emitBare } from "bailian-cli-runtime";
+import { resolveWorkspaceId, WORKSPACE_FLAG } from "./shared.ts";
+
+const BOOL_CHOICES = ["true", "false"];
+
+const SERVICE_UPDATE_FLAGS = {
+  agentId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Service (agent) ID",
+    required: true,
+  },
+  name: {
+    type: "string",
+    valueHint: "<text>",
+    description: "New service name (up to 200 chars)",
+  },
+  description: {
+    type: "string",
+    valueHint: "<text>",
+    description: "New service description (up to 1000 chars)",
+  },
+  agentVersion: {
+    type: "string",
+    valueHint: "<version>",
+    description:
+      "Target version (default: beta draft). Published versions only accept --version-desc",
+  },
+  versionDesc: {
+    type: "string",
+    valueHint: "<text>",
+    description: "Version description",
+  },
+  policy: {
+    type: "string",
+    valueHint: "<policy>",
+    description: "Agent policy: turbo (fast) or agentic (multi-turn)",
+  },
+  model: {
+    type: "string",
+    valueHint: "<name>",
+    description: "Generation model code (must be in the platform allowlist)",
+  },
+  temperature: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Sampling temperature, range 0-2",
+  },
+  maxLlmCalls: {
+    type: "number",
+    valueHint: "<n>",
+    description: "Max LLM calls per request, range 1-30",
+  },
+  enableSessionFile: {
+    type: "string",
+    valueHint: "<bool>",
+    description: "Enable session files: true or false",
+  },
+  enableRefusal: {
+    type: "string",
+    valueHint: "<bool>",
+    description: "Enable refusal answers: true or false",
+  },
+  enableAntiLeak: {
+    type: "string",
+    valueHint: "<bool>",
+    description: "Enable anti prompt-leak: true or false",
+  },
+  enableRichText: {
+    type: "string",
+    valueHint: "<bool>",
+    description: "Enable rich text output: true or false",
+  },
+  enableCitation: {
+    type: "string",
+    valueHint: "<bool>",
+    description: "Enable citations: true or false",
+  },
+  configFile: {
+    type: "string",
+    valueHint: "<path>",
+    description:
+      "JSON file replacing the whole agent_config (for nested settings like kb_search_configs); mutually exclusive with scalar config flags",
+  },
+  ...WORKSPACE_FLAG,
+} satisfies FlagsDef;
+
+type UpdateFlags = {
+  policy?: string;
+  model?: string;
+  temperature?: number;
+  maxLlmCalls?: number;
+  enableSessionFile?: string;
+  enableRefusal?: string;
+  enableAntiLeak?: string;
+  enableRichText?: string;
+  enableCitation?: string;
+};
+
+/** Scalar config flag → agent_config field mapping (centralized for validation and merge) */
+function collectScalarConfig(flags: UpdateFlags): Partial<RagAgentConfig> {
+  const scalar: Partial<RagAgentConfig> = {};
+  if (flags.policy !== undefined) scalar.agent_policy = flags.policy;
+  if (flags.model !== undefined) scalar.agent_model = flags.model;
+  if (flags.temperature !== undefined) scalar.temperature = flags.temperature;
+  if (flags.maxLlmCalls !== undefined) scalar.max_num_llm_calls = flags.maxLlmCalls;
+  if (flags.enableSessionFile !== undefined) scalar.enable_session_file = flags.enableSessionFile;
+  if (flags.enableRefusal !== undefined) scalar.enable_refusal = flags.enableRefusal;
+  if (flags.enableAntiLeak !== undefined) scalar.enable_anti_leak = flags.enableAntiLeak;
+  if (flags.enableRichText !== undefined) scalar.enable_rich_text = flags.enableRichText;
+  if (flags.enableCitation !== undefined) scalar.enable_citation = flags.enableCitation;
+  return scalar;
+}
+
+/** --config-file: read JSON + structural/enum/range validation; unknown fields warn but pass through */
+export function parseConfigFile(filePath: string): RagAgentConfig {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (error) {
+    const errno = (error as { code?: string }).code ?? "unknown";
+    throw new BailianError(
+      `Cannot read config file: ${filePath}`,
+      ExitCode.GENERAL,
+      `File system error (${errno}) — check the path and permissions.`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new BailianError("--config-file must contain valid JSON.", ExitCode.USAGE);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new BailianError("--config-file must contain a JSON object.", ExitCode.USAGE);
+  }
+  const config = parsed as RagAgentConfig;
+  validateConfigValues(config);
+  return config;
+}
+
+const KNOWN_CONFIG_KEYS = new Set([
+  "agent_policy",
+  "agent_model",
+  "enable_session_file",
+  "enable_refusal",
+  "enable_anti_leak",
+  "enable_rich_text",
+  "enable_citation",
+  "temperature",
+  "max_num_llm_calls",
+  "max_completion_tokens",
+  "session_file_max_parse_length",
+  "enable_kb_router",
+  "kb_router_model",
+  "rerank_top_n",
+  "hybrid_rerank",
+  "kb_search_configs",
+]);
+
+/** Enum/range validation + behavioral warnings, per the agent_config contract */
+export function validateConfigValues(config: RagAgentConfig): void {
+  if (config.agent_policy !== undefined && !["turbo", "agentic"].includes(config.agent_policy)) {
+    throw new BailianError("agent_policy must be turbo or agentic", ExitCode.USAGE);
+  }
+  if (config.temperature !== undefined && (config.temperature < 0 || config.temperature > 2)) {
+    throw new BailianError("temperature must be between 0 and 2", ExitCode.USAGE);
+  }
+  if (
+    config.max_num_llm_calls !== undefined &&
+    (config.max_num_llm_calls < 1 || config.max_num_llm_calls > 30)
+  ) {
+    throw new BailianError("max_num_llm_calls must be between 1 and 30", ExitCode.USAGE);
+  }
+  if (config.rerank_top_n !== undefined && (config.rerank_top_n < 1 || config.rerank_top_n > 20)) {
+    throw new BailianError("rerank_top_n must be between 1 and 20", ExitCode.USAGE);
+  }
+  // Behavioral warning: the server clears rerank_instruct unless rerank_mode is custom
+  for (const kbConfig of config.kb_search_configs ?? []) {
+    const rerank = kbConfig.rerank as
+      | { rerank_mode?: string; rerank_instruct?: string }
+      | undefined;
+    if (rerank?.rerank_instruct && rerank.rerank_mode !== "custom") {
+      process.stderr.write(
+        "Warning: rerank_instruct is only effective with rerank_mode=custom; the server clears it otherwise.\n",
+      );
+    }
+  }
+  // Unknown fields: warn but pass through (the server is the source of truth)
+  for (const key of Object.keys(config)) {
+    if (!KNOWN_CONFIG_KEYS.has(key)) {
+      process.stderr.write(`Warning: unknown agent_config field passed through: ${key}\n`);
+    }
+  }
+}
+
+/** read-merge-write: fetch the full beta-draft config and merge scalar changes (the API has whole-replace semantics) */
+async function fetchBetaConfig(
+  client: Client,
+  workspaceId: string,
+  agentId: string,
+): Promise<RagAgentConfig> {
+  const response = await client.requestJson<RagAgentGetResponse>({
+    path: ragEndpoint(workspaceId, RAG_PATHS.agentGet),
+    method: "POST",
+    body: { agent_id: agentId, agent_version: "beta" },
+  });
+  const betaDetail = (response.data?.agent_details ?? []).find(
+    (detail) => detail.agent_version === "beta",
+  );
+  return betaDetail?.agent_config ?? {};
+}
+
+export default defineCommand({
+  description: "Update service name, description or draft configuration",
+  auth: "apiKey",
+  usageArgs: "--agent-id <id> [flags]",
+  flags: SERVICE_UPDATE_FLAGS,
+  notes: [
+    "Configuration changes only apply to the beta draft; published versions accept --version-desc only.",
+    "To change the configuration of a published version, first update the beta draft (this command without --agent-version or with --agent-version beta), then run service deploy to publish a new version.",
+    "Scalar config flags merge into the current draft config (read-merge-write); --config-file replaces the whole config and is mutually exclusive with them.",
+    "After updating the draft, verify with --agent-version beta on search/chat, then deploy.",
+    "Requires the knowledge-base modify permission in the workspace.",
+  ],
+  // Note on `agent_version` in the request body: this is the agent-management
+  // domain's "target version" parameter (beta draft or a published version
+  // number). It is NOT the search/chat debug-draft field that the project-wide
+  // agent_version cleanup removes — the two share a name but live in different
+  // API surfaces and have different semantics.
+  exampleArgs: [
+    "--agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx",
+    "--agent-id aid-xxx --config-file ./agent-config.json",
+    "--agent-id aid-xxx --agent-version 1 --version-desc 'first stable release'",
+  ],
+  validate(flags) {
+    const scalarTouched = Object.keys(collectScalarConfig(flags)).length > 0;
+    const anyChange =
+      flags.name !== undefined ||
+      flags.description !== undefined ||
+      flags.versionDesc !== undefined ||
+      flags.configFile !== undefined ||
+      scalarTouched;
+    if (!anyChange)
+      return "Nothing to update — pass a name/description/version-desc or config flags";
+    if (flags.configFile !== undefined && scalarTouched) {
+      return "--config-file is mutually exclusive with scalar config flags";
+    }
+    // Version check up front: published version + config change → USAGE (the server
+    // would also reject it, but failing early is faster)
+    const publishedVersion = flags.agentVersion !== undefined && flags.agentVersion !== "beta";
+    if (publishedVersion && (scalarTouched || flags.configFile !== undefined)) {
+      return "Published versions only accept --version-desc; update the beta draft to change config";
+    }
+    if (flags.name !== undefined && flags.name.length > 200) {
+      return "--name must be at most 200 characters";
+    }
+    if (flags.description !== undefined && flags.description.length > 1000) {
+      return "--description must be at most 1000 characters";
+    }
+    if (flags.policy !== undefined && !["turbo", "agentic"].includes(flags.policy)) {
+      return "--policy must be turbo or agentic";
+    }
+    if (flags.temperature !== undefined && (flags.temperature < 0 || flags.temperature > 2)) {
+      return "--temperature must be between 0 and 2";
+    }
+    if (flags.maxLlmCalls !== undefined && (flags.maxLlmCalls < 1 || flags.maxLlmCalls > 30)) {
+      return "--max-llm-calls must be between 1 and 30";
+    }
+    for (const [flagName, value] of [
+      ["--enable-session-file", flags.enableSessionFile],
+      ["--enable-refusal", flags.enableRefusal],
+      ["--enable-anti-leak", flags.enableAntiLeak],
+      ["--enable-rich-text", flags.enableRichText],
+      ["--enable-citation", flags.enableCitation],
+    ] as const) {
+      if (value !== undefined && !BOOL_CHOICES.includes(value)) {
+        return `${flagName} must be true or false`;
+      }
+    }
+    return undefined;
+  },
+  async run(ctx) {
+    const { settings, flags } = ctx;
+    const workspaceId = resolveWorkspaceId(ctx);
+    const format = detectOutputFormat(settings.output);
+
+    const scalarConfig = collectScalarConfig(flags);
+    const hasConfigChange = flags.configFile !== undefined || Object.keys(scalarConfig).length > 0;
+
+    let agentConfig: RagAgentConfig | undefined;
+    if (flags.configFile !== undefined) {
+      // dry-run also reads the file and validates (rehearsal semantics)
+      agentConfig = parseConfigFile(flags.configFile);
+    } else if (Object.keys(scalarConfig).length > 0) {
+      if (settings.dryRun) {
+        // dry-run does not issue the read-merge request; show the scalar delta with a placeholder note
+        agentConfig = { ...scalarConfig };
+      } else {
+        // The API has whole-replace semantics — read the full beta config first,
+        // then merge (hidden from the user)
+        const currentConfig = await fetchBetaConfig(ctx.client, workspaceId, flags.agentId);
+        agentConfig = { ...currentConfig, ...scalarConfig };
+        validateConfigValues(agentConfig);
+      }
+    }
+
+    const body = {
+      agent_id: flags.agentId,
+      ...(flags.name !== undefined ? { agent_name: flags.name } : {}),
+      ...(flags.description !== undefined ? { agent_desc: flags.description } : {}),
+      ...(flags.agentVersion !== undefined ? { agent_version: flags.agentVersion } : {}),
+      ...(flags.versionDesc !== undefined ? { agent_version_desc: flags.versionDesc } : {}),
+      ...(agentConfig !== undefined ? { agent_config: agentConfig } : {}),
+    };
+    const endpoint = ragEndpoint(workspaceId, RAG_PATHS.agentUpdate);
+
+    if (settings.dryRun) {
+      emitResult(
+        {
+          endpoint,
+          request: body,
+          ...(hasConfigChange && flags.configFile === undefined
+            ? { note: "scalar config flags are merged into the current beta config at run time" }
+            : {}),
+        },
+        format,
+      );
+      return;
+    }
+
+    const response = await ctx.client.requestJson<RagAgentMutationResponse>({
+      path: endpoint,
+      method: "POST",
+      body,
+    });
+
+    if (settings.quiet) return;
+    if (format === "text") {
+      emitBare(`updated: ${flags.agentId}`);
+      if (hasConfigChange) {
+        emitBare("Draft config changed — verify with --agent-version beta, then deploy.");
+      }
+      return;
+    }
+    emitResult(response, format);
+  },
+});
diff --git a/packages/commands/src/commands/knowledge/shared.ts b/packages/commands/src/commands/knowledge/shared.ts
new file mode 100644
index 00000000..1e2cae35
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/shared.ts
@@ -0,0 +1,183 @@
+// Shared building blocks for the knowledge admin commands.
+import {
+  BailianError,
+  ExitCode,
+  ragEndpoint,
+  RAG_PATHS,
+  type Client,
+  type FlagsDef,
+  type RagIndexJobDoc,
+  type RagIndexJobStatusResponse,
+  type Settings,
+} from "bailian-cli-core";
+import { poll } from "bailian-cli-runtime";
+
+// Knowledge APIs use a workspace-specific host, so --workspace-id is a per-command
+// flag here (the console credential scope does not apply).
+export const WORKSPACE_FLAG = {
+  workspaceId: {
+    type: "string",
+    valueHint: "<id>",
+    description: "Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)",
+  },
+} satisfies FlagsDef;
+
+// Unified pagination flags for admin list commands. The server-side page/size
+// parameter names differ per endpoint (page_number/page_num/pageNum/pageNumber…)
+// and the body-vs-query-string placement also varies — each command maps these
+// flags to its own API contract. Never pass the flag names through verbatim;
+// the CLI-facing flag vocabulary is stable even when the backend is not.
+export const PAGE_FLAGS = {
+  pageNumber: { type: "number", valueHint: "<n>", description: "Page number (default: 1)" },
+  pageSize: { type: "number", valueHint: "<n>", description: "Page size per request" },
+} satisfies FlagsDef;
+
+/** Three-level fallback: flag > BAILIAN_WORKSPACE_ID env > config (env/config are merged into settings); missing → USAGE. */
+export function resolveWorkspaceId(ctx: {
+  flags: { workspaceId?: string };
+  settings: { workspaceId?: string };
+  identity: { binName: string };
+}): string {
+  const workspaceId = ctx.flags.workspaceId || ctx.settings.workspaceId;
+  if (!workspaceId) {
+    throw new BailianError(
+      "Workspace ID is required.",
+      ExitCode.USAGE,
+      `Pass --workspace-id, set BAILIAN_WORKSPACE_ID env, or configure: ${ctx.identity.binName} config set workspace_id <id>`,
+    );
+  }
+  return workspaceId;
+}
+
+/** Truncate text-mode table rows to the terminal width; no truncation when not a TTY (pipe/redirect). */
+export function truncateLine(line: string): string {
+  if (!process.stdout.isTTY) return line;
+  const width = process.stdout.columns ?? 120;
+  return line.length > width ? `${line.slice(0, Math.max(0, width - 1))}…` : line;
+}
+
+// ---- Shared import-job (index_job/status) logic ----
+// Verified against the live API: the overall job state lives in `ingestion_status`
+// (PENDING/RUNNING/COMPLETED, no FAILED value); the per-document list is `rows[]`
+// and failures surface via `rows[].code` (e.g. PARSE_FAILED).
+// Shared by doc status / doc upload / kb create — contract changes only touch this file.
+
+/** Overall job state (ingestion_status) */
+export function importJobStatus(response: unknown): string {
+  return (response as RagIndexJobStatusResponse).data?.ingestion_status ?? "UNKNOWN";
+}
+
+/** Per-document failures: rows[].code / status containing FAILED */
+export function failedImportDocs(response: RagIndexJobStatusResponse): RagIndexJobDoc[] {
+  return (response.data?.rows ?? []).filter((doc) =>
+    [doc.code, doc.status].some((value) => typeof value === "string" && value.includes("FAILED")),
+  );
+}
+
+/**
+ * Whether every document has reached a terminal state (FINISH or *FAILED).
+ * Used to stop polling before ingestion_status becomes COMPLETED — the server
+ * may leave the job on RUNNING indefinitely even after all documents finish.
+ */
+function allDocsTerminal(response: RagIndexJobStatusResponse): boolean {
+  const rows = response.data?.rows ?? [];
+  if (rows.length === 0) return false;
+  const totalCount = response.data?.total_count;
+  if (typeof totalCount === "number" && rows.length < totalCount) return false;
+  return rows.every((doc) => {
+    const code = doc.code ?? doc.status ?? "";
+    return code === "FINISH" || code.includes("FAILED");
+  });
+}
+
+/** Per-document failure summary: lists both failed and succeeded documents so the user knows the full picture. */
+export function importJobFailureMessage(
+  response: RagIndexJobStatusResponse,
+  fallbackMessage: string,
+): string {
+  const rows = response.data?.rows ?? [];
+  const failed = failedImportDocs(response);
+  const failedIds = new Set(failed.map((doc) => doc.doc_id));
+  const succeeded = rows.filter((doc) => !failedIds.has(doc.doc_id));
+
+  const failedDetail = failed
+    .map((doc) => `${doc.doc_name ?? doc.doc_id ?? "?"}: ${doc.message ?? doc.code ?? "unknown"}`)
+    .join("; ");
+  const succeededDetail = succeeded.map((doc) => doc.doc_name ?? doc.doc_id ?? "?").join(", ");
+
+  const parts: string[] = [];
+  if (failedDetail) parts.push(`failed: ${failedDetail}`);
+  if (succeededDetail) parts.push(`succeeded: ${succeededDetail}`);
+
+  return parts.length > 0 ? `${fallbackMessage} (${parts.join("; ")})` : fallbackMessage;
+}
+
+/** Build the index_job/status query string (both index_id and job_id are required) */
+export function importJobStatusUrl(workspaceId: string, indexId: string, jobId: string): URL {
+  const url = new URL(ragEndpoint(workspaceId, RAG_PATHS.indexJobStatus));
+  url.searchParams.set("index_id", indexId);
+  url.searchParams.set("job_id", jobId);
+  return url;
+}
+
+/**
+ * Poll the import job until the overall state is COMPLETED or every document
+ * has reached a terminal state (FINISH or FAILED). The overall state has no
+ * FAILED value, so isFailed is always false — failures are determined by the
+ * caller after return via `failedImportDocs`. The server may leave
+ * ingestion_status on RUNNING indefinitely after documents finish, so checking
+ * rows[] mid-poll avoids a misleading timeout; callers re-check failedImportDocs
+ * after return, keeping the error path uniform.
+ */
+export async function pollImportJob(
+  client: Client,
+  settings: Settings,
+  options: { statusUrl: string; intervalSec: number },
+): Promise<RagIndexJobStatusResponse> {
+  return poll<RagIndexJobStatusResponse>(client, settings, {
+    url: options.statusUrl,
+    intervalSec: options.intervalSec,
+    timeoutSec: settings.timeout,
+    isComplete: (data) => {
+      const response = data as RagIndexJobStatusResponse;
+      return importJobStatus(response) === "COMPLETED" || allDocsTerminal(response);
+    },
+    isFailed: () => false,
+    getStatus: (data) => {
+      const response = data as RagIndexJobStatusResponse;
+      const status = importJobStatus(response);
+      const failedCount = failedImportDocs(response).length;
+      const total = response.data?.total_count;
+      if (typeof total === "number" && total > 0) {
+        return `${status} (${failedCount}/${total} failed)`;
+      }
+      return failedCount > 0 ? `${status} (${failedCount} failed)` : status;
+    },
+  });
+}
+
+/** Attach a hint for partial-success cases while preserving server context (api/rawResponse kept) */
+export function withPartialSuccessHint(error: unknown, hint: string): unknown {
+  if (!(error instanceof BailianError) || error.hint) return error;
+  return new BailianError(error.message, error.exitCode, hint, {
+    cause: error,
+    api: error.api,
+    rawResponse: error.rawResponse,
+  });
+}
+
+/**
+ * Read response fields from agent-domain mutation endpoints. Gotcha verified
+ * against the live API: create/copy return agent_id etc. inside data, but
+ * deploy returns agent_version/agent_status at the top level next to code —
+ * the server envelope is inconsistent, so read both locations defensively.
+ */
+export function agentMutationField(
+  response: { data?: Record<string, unknown>; [key: string]: unknown },
+  field: "agent_id" | "agent_name" | "agent_version" | "agent_status",
+): string | undefined {
+  const nested = response.data?.[field];
+  if (typeof nested === "string") return nested;
+  const topLevel = response[field];
+  return typeof topLevel === "string" ? topLevel : undefined;
+}
diff --git a/packages/commands/src/commands/knowledge/upload-support.ts b/packages/commands/src/commands/knowledge/upload-support.ts
new file mode 100644
index 00000000..97a519ca
--- /dev/null
+++ b/packages/commands/src/commands/knowledge/upload-support.ts
@@ -0,0 +1,236 @@
+// Local pre-flight validation for file uploads (doc upload).
+// Default category: the lease/addFile `category` parameter accepts the literal
+// "default" (verified against the live API), so no listCategory resolution is needed.
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+const MB = 1024 * 1024;
+
+export interface UploadFormatRule {
+  maxBytes: number;
+  /** block: exceeding the limit throws USAGE; warn: only a stderr warning (documented as a recommended limit) */
+  enforce: "block" | "warn";
+}
+
+/**
+ * Format allowlist based on the officially supported document formats.
+ * .csv is inconsistent across the public docs — kept in the allowlist for now;
+ * a server-side rejection would be passed through verbatim.
+ */
+export const UPLOAD_FORMAT_RULES: Record<string, UploadFormatRule> = {
+  ".doc": { maxBytes: 150 * MB, enforce: "block" },
+  ".docx": { maxBytes: 150 * MB, enforce: "block" },
+  ".ppt": { maxBytes: 150 * MB, enforce: "block" },
+  ".pptx": { maxBytes: 150 * MB, enforce: "block" },
+  ".pdf": { maxBytes: 150 * MB, enforce: "block" },
+  ".png": { maxBytes: 20 * MB, enforce: "block" },
+  ".jpg": { maxBytes: 20 * MB, enforce: "block" },
+  ".jpeg": { maxBytes: 20 * MB, enforce: "block" },
+  ".bmp": { maxBytes: 20 * MB, enforce: "block" },
+  ".gif": { maxBytes: 20 * MB, enforce: "block" },
+  ".xls": { maxBytes: 10 * MB, enforce: "warn" },
+  ".xlsx": { maxBytes: 10 * MB, enforce: "warn" },
+  ".csv": { maxBytes: 10 * MB, enforce: "warn" },
+  ".md": { maxBytes: 10 * MB, enforce: "warn" },
+  ".txt": { maxBytes: 10 * MB, enforce: "warn" },
+  ".html": { maxBytes: 10 * MB, enforce: "warn" },
+};
+
+/** Returns true when the extension is in the upload format allowlist. */
+export function isSupportedExtension(filePath: string): boolean {
+  const extension = extname(filePath).toLowerCase();
+  return extension in UPLOAD_FORMAT_RULES;
+}
+
+/**
+ * Directory names skipped when expanding a directory path (recursive scan).
+ * Covers common tooling artifacts that should never contain user documents.
+ */
+const IGNORED_DIRECTORIES = new Set([
+  "node_modules",
+  ".git",
+  ".svn",
+  ".hg",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".env",
+  ".tox",
+  "dist",
+  "build",
+  ".cache",
+  ".next",
+  ".nuxt",
+]);
+
+export interface ExpandResult {
+  files: string[];
+  skipped: string[];
+}
+
+/**
+ * Expand an array of paths into individual file paths.
+ * - Regular files are included as-is.
+ * - Directories are recursively scanned; files with unsupported extensions are
+ *   collected into `skipped` instead of throwing.
+ * - Common tooling directories (node_modules, .git, …) are silently skipped.
+ * - A non-existent path throws USAGE so the user gets a clear error.
+ */
+export function expandUploadPaths(paths: string[]): ExpandResult {
+  const files: string[] = [];
+  const skipped: string[] = [];
+
+  function walkDirectory(directoryPath: string): void {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(directoryPath, { withFileTypes: true });
+    } catch (error) {
+      const errno = (error as { code?: string }).code ?? "unknown";
+      throw new BailianError(
+        `Cannot read directory: ${directoryPath}`,
+        ExitCode.GENERAL,
+        `File system error (${errno}) — check the path and permissions.`,
+      );
+    }
+    for (const entry of entries) {
+      const entryFullPath = join(directoryPath, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) {
+          walkDirectory(entryFullPath);
+        }
+        continue;
+      }
+      if (entry.isFile()) {
+        if (isSupportedExtension(entry.name)) {
+          files.push(entryFullPath);
+        } else {
+          skipped.push(entryFullPath);
+        }
+      }
+      // Symlinks: withFileTypes follows symlinks for isFile/isDirectory,
+      // so they are handled by the branches above.
+    }
+  }
+
+  for (const inputPath of paths) {
+    let pathStat: import("node:fs").Stats;
+    try {
+      pathStat = statSync(inputPath);
+    } catch (error) {
+      const errno = (error as { code?: string }).code ?? "unknown";
+      throw new BailianError(
+        `Cannot read path: ${inputPath}`,
+        ExitCode.GENERAL,
+        `File system error (${errno}) — check the path and permissions.`,
+      );
+    }
+    if (pathStat.isDirectory()) {
+      walkDirectory(inputPath);
+    } else if (pathStat.isFile()) {
+      files.push(inputPath);
+    }
+    // Other types (socket, block device, etc.) are silently ignored.
+  }
+
+  return { files, skipped };
+}
+
+/** Local pre-flight check before reading the file: extension allowlist + hard/soft size limits. File I/O failure → GENERAL + errno hint. */
+export function checkUploadFile(filePath: string): { sizeBytes: number; warning?: string } {
+  const extension = extname(filePath).toLowerCase();
+  const rule = UPLOAD_FORMAT_RULES[extension];
+  if (!rule) {
+    throw new BailianError(
+      `Unsupported file type: ${extension || basename(filePath)}`,
+      ExitCode.USAGE,
+      `Supported formats: ${Object.keys(UPLOAD_FORMAT_RULES).join(" ")}`,
+    );
+  }
+  let sizeBytes: number;
+  try {
+    sizeBytes = statSync(filePath).size;
+  } catch (error) {
+    const errno = (error as { code?: string }).code ?? "unknown";
+    throw new BailianError(
+      `Cannot read file: ${filePath}`,
+      ExitCode.GENERAL,
+      `File system error (${errno}) — check the path and permissions.`,
+    );
+  }
+  if (sizeBytes > rule.maxBytes) {
+    const limitMb = rule.maxBytes / MB;
+    if (rule.enforce === "block") {
+      throw new BailianError(
+        `File exceeds the ${limitMb} MB limit for ${extension}: ${basename(filePath)}`,
+        ExitCode.USAGE,
+      );
+    }
+    return {
+      sizeBytes,
+      warning: `${basename(filePath)} exceeds the recommended 10 MB for ${extension}; the server may reject or truncate it.`,
+    };
+  }
+  return { sizeBytes };
+}
+
+// Known document-format extensions — used to tailor the hint on decode failure
+// (pointing users to the document upload flow instead)
+const DOCUMENT_EXTENSIONS = new Set([
+  ".doc",
+  ".docx",
+  ".ppt",
+  ".pptx",
+  ".pdf",
+  ".xls",
+  ".xlsx",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".bmp",
+  ".gif",
+]);
+
+/**
+ * Read a UTF-8 plain-text file.
+ * Support is defined by content, not extension: any UTF-8 text is valid.
+ * Strict decode failure → USAGE, with a hint pointing to the document upload
+ * flow when the extension is a document format; file I/O failure → GENERAL + errno.
+ *
+ * @param inlineAlternativeFlag When provided, an ENOENT on a value that looks
+ *   like inline text (no path separator / no extension) appends a hint pointing
+ *   the user to this flag instead. Pass the inline-text flag name (e.g.
+ *   `"--content"`) only from commands that have a file-vs-inline choice.
+ */
+export function readUtf8TextFile(filePath: string, inlineAlternativeFlag?: string): string {
+  let fileBuffer: Buffer;
+  try {
+    fileBuffer = readFileSync(filePath);
+  } catch (error) {
+    const errno = (error as { code?: string }).code ?? "unknown";
+    let hint = `File system error (${errno}) — check the path and permissions.`;
+    if (
+      inlineAlternativeFlag &&
+      errno === "ENOENT" &&
+      !extname(filePath) &&
+      !filePath.includes("/") &&
+      !filePath.includes("\\")
+    ) {
+      hint += ` If you meant to pass text content directly, use ${inlineAlternativeFlag} instead of --content-file.`;
+    }
+    throw new BailianError(`Cannot read file: ${filePath}`, ExitCode.GENERAL, hint);
+  }
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(fileBuffer);
+  } catch {
+    const extension = extname(filePath).toLowerCase();
+    const hint = DOCUMENT_EXTENSIONS.has(extension)
+      ? "Document formats cannot be used as chunk content. Upload documents via the document upload command; to edit a chunk, save the text as .md/.txt first."
+      : "Convert the file to UTF-8 encoding and retry.";
+    throw new BailianError(
+      `File is not valid UTF-8 plain text: ${basename(filePath)}`,
+      ExitCode.USAGE,
+      hint,
+    );
+  }
+}
diff --git a/packages/commands/src/index.ts b/packages/commands/src/index.ts
index 19aae774..9ce7a9e9 100644
--- a/packages/commands/src/index.ts
+++ b/packages/commands/src/index.ts
@@ -36,6 +36,37 @@ export { default as memoryProfileGet } from "./commands/memory/profile-get.ts";
 export { default as knowledgeRetrieve } from "./commands/knowledge/retrieve.ts";
 export { default as knowledgeSearch } from "./commands/knowledge/search.ts";
 export { default as knowledgeChat } from "./commands/knowledge/chat.ts";
+export { default as knowledgeKbList } from "./commands/knowledge/kb-list.ts";
+export { default as knowledgeKbInfo } from "./commands/knowledge/kb-info.ts";
+export { default as knowledgeDocList } from "./commands/knowledge/doc-list.ts";
+export { default as knowledgeDocStatus } from "./commands/knowledge/doc-status.ts";
+export { default as knowledgeDocUpload } from "./commands/knowledge/doc-upload.ts";
+export { default as knowledgeKbCreate } from "./commands/knowledge/kb-create.ts";
+export { default as knowledgeKbUpdate } from "./commands/knowledge/kb-update.ts";
+export { default as knowledgeKbDelete } from "./commands/knowledge/kb-delete.ts";
+export { default as knowledgeDocDelete } from "./commands/knowledge/doc-delete.ts";
+export { default as knowledgeDocTag } from "./commands/knowledge/doc-tag.ts";
+export { default as knowledgeServiceList } from "./commands/knowledge/service-list.ts";
+export { default as knowledgeServiceGet } from "./commands/knowledge/service-get.ts";
+export { default as knowledgeServiceCreate } from "./commands/knowledge/service-create.ts";
+export { default as knowledgeServiceUpdate } from "./commands/knowledge/service-update.ts";
+export { default as knowledgeServiceDeploy } from "./commands/knowledge/service-deploy.ts";
+export { default as knowledgeServiceDelete } from "./commands/knowledge/service-delete.ts";
+export { default as knowledgeServiceCopy } from "./commands/knowledge/service-copy.ts";
+export { default as knowledgeChunkAdd } from "./commands/knowledge/chunk-add.ts";
+export { default as knowledgeChunkList } from "./commands/knowledge/chunk-list.ts";
+export { default as knowledgeChunkUpdate } from "./commands/knowledge/chunk-update.ts";
+export { default as knowledgeChunkDelete } from "./commands/knowledge/chunk-delete.ts";
+export { default as knowledgeKbStats } from "./commands/knowledge/kb-stats.ts";
+export { default as knowledgeCategoryList } from "./commands/knowledge/category-list.ts";
+export { default as knowledgeCategoryAdd } from "./commands/knowledge/category-add.ts";
+export { default as knowledgeCategoryDelete } from "./commands/knowledge/category-delete.ts";
+export { default as knowledgeFileList } from "./commands/knowledge/file-list.ts";
+export { default as knowledgeFileGet } from "./commands/knowledge/file-get.ts";
+export { default as knowledgeFileDelete } from "./commands/knowledge/file-delete.ts";
+export { default as knowledgeCollectionCreate } from "./commands/knowledge/collection-create.ts";
+export { default as knowledgeCollectionGet } from "./commands/knowledge/collection-get.ts";
+export { default as knowledgeDocImportOss } from "./commands/knowledge/doc-import-oss.ts";
 export { default as mcpCall } from "./commands/mcp/call.ts";
 export { default as mcpList } from "./commands/mcp/list.ts";
 export { default as mcpTools } from "./commands/mcp/tools.ts";
diff --git a/packages/commands/tests/e2e/auth.e2e.test.ts b/packages/commands/tests/e2e/auth.e2e.test.ts
index cfb719b6..3e60d3e9 100644
--- a/packages/commands/tests/e2e/auth.e2e.test.ts
+++ b/packages/commands/tests/e2e/auth.e2e.test.ts
@@ -20,6 +20,7 @@ interface ValidationServer {
     body: Record<string, unknown>;
     authorization?: string;
     sourceConfig?: string;
+    openApiSource?: string;
   }>;
   close(): Promise<void>;
 }
@@ -36,6 +37,7 @@ async function startValidationServer(statusCode = 200): Promise<ValidationServer
         body: rawBody ? (JSON.parse(rawBody) as Record<string, unknown>) : {},
         authorization: request.headers.authorization,
         sourceConfig: request.headers["x-dashscope-source-config"] as string | undefined,
+        openApiSource: request.headers["x-dashscope-openapisource"] as string | undefined,
       });
       response.writeHead(statusCode, { "Content-Type": "application/json" });
       if (statusCode >= 400) {
@@ -216,6 +218,7 @@ describe("e2e: auth", () => {
         path: "/compatible-mode/v1/chat/completions",
         authorization: "Bearer sk-e2e-placeholder",
         sourceConfig: expect.any(String),
+        openApiSource: "BailianCLI",
         body: {
           model: "qwen3.8-max",
           stream: false,
@@ -313,6 +316,7 @@ describe("e2e: auth", () => {
         path: "/compatible-mode/v1/chat/completions",
         authorization: "Bearer sk-sp-e2e-placeholder",
         sourceConfig: expect.any(String),
+        openApiSource: "BailianCLI",
         body: {
           model: "qwen3.8-max",
           stream: false,
diff --git a/packages/commands/tests/e2e/helpers.ts b/packages/commands/tests/e2e/helpers.ts
index 68e82b9f..a81f08ee 100644
--- a/packages/commands/tests/e2e/helpers.ts
+++ b/packages/commands/tests/e2e/helpers.ts
@@ -26,10 +26,18 @@ export {
   isBailianE2EMediaEnabled,
   isBailianE2EVideoEnabled,
   isChatE2EReady,
+  isConnectorE2EReady,
   isConsoleE2EReady,
   isDashScopeE2EReady,
+  isImageKbE2EReady,
+  isKbAdminE2EReady,
+  isMultimodalChatE2EReady,
+  isMultimodalSearchE2EReady,
   isOpenApiE2EReady,
+  isOssImportE2EReady,
   isSearchE2EReady,
+  isTableKbE2EReady,
+  isTableSearchE2EReady,
 } from "e2e/gating";
 
 const e2eDir = dirname(fileURLToPath(import.meta.url));
diff --git a/packages/commands/tests/e2e/knowledge/journeys/README.md b/packages/commands/tests/e2e/knowledge/journeys/README.md
new file mode 100644
index 00000000..210074a1
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/README.md
@@ -0,0 +1,34 @@
+# Journey E2E（用户旅程链路测试）
+
+从用户 case 出发验证关键流程可用性：每条 journey = 用户带着一个目标跨命令走完整回路，
+以「fixture 标记词能否被召回」判定回路闭合（区别于 `../*.e2e.test.ts` 的单命令契约测试）。
+
+## 旅程映射
+
+| #   | 用户 Case                            | 文件                                                                                    | 闭环断言                                                                                                                |
+| --- | ------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| J1  | 冷启动：建库并获得首个答案           | `j1-cold-start.e2e.test.ts`                                                             | retrieve/search(beta) 召回标记词（硬）；chat 回答引用标记词（软）                                                       |
+| J2  | 内容运维：文档增删的可见性           | `j2-content-ops.e2e.test.ts`                                                            | 双标记词命中 → 删除其一后 markerB 消失且 markerA 仍在（硬）                                                             |
+| J3  | 检索精修：chunk 排除生效             | `j3-chunk-tuning.e2e.test.ts`                                                           | exclude 后排除标志生效（硬）；include 恢复（软）。retrieve 不过滤被排除 chunk，以 `is_displayed_chunk_content` 标志为准 |
+| J4  | 服务调优：草稿→修改→发布             | `j4-service-tuning.e2e.test.ts`                                                         | beta 草稿可用、update 落库、发布后正式版详情携带修改且可用（硬）                                                        |
+| J5  | 数据面治理：collection/category/file | `j5-data-plane.e2e.test.ts`                                                             | 自建类目内文件可见/可删，类目删后消失（硬）                                                                             |
+| J6  | 退场清理：删库验证消失               | 复用 [`../knowledge-kb-delete.e2e.test.ts`](../knowledge-kb-delete.e2e.test.ts) live 链 | delete 后 list 不再包含（硬）                                                                                           |
+
+## 约定
+
+- **gating**：J1–J4 `isKbAdminE2EReady()`；J5 `isConnectorE2EReady()`（collection 无删除 API，仅手动开启；gating 函数/环境变量保留 CONNECTOR 旧名）。
+- **自建自清**：所有资源自建 + `try/finally` 清理；kb 删除走 `deleteKbWithRetry`（IndexStatusError 重试）；
+  数据中心文件用 `knowledge file delete` 回收；清理失败不掩盖，落 `resources.json` 供人工回收。
+- **软/硬断言**：可用性关键路径硬断言（fail）；依赖服务端语义/延迟波动的信号软断言
+  （`recordSoft`，只落报告不 fail，人工复核）。
+- **日志产物**：每次 live 运行在 `test/output/<session>/e2e-vp-<journey>-<ts>/` 生成
+  `journey-report.md`（步骤表 + 软断言区 + 未清理资源警示）、分步 stdout/stderr、`resources.json`、`journey.log`。
+
+## 运行
+
+```sh
+pnpm run test:journey            # 全部 journey（无凭证时全部 skip）
+vp test packages/commands/tests/e2e/knowledge/journeys/j1-cold-start.e2e.test.ts
+```
+
+live 运行需 `.env`：`BAILIAN_E2E=1` + DashScope API key + `BAILIAN_WORKSPACE_ID`；J5 另需 `BAILIAN_E2E_CONNECTOR=1`。
diff --git a/packages/commands/tests/e2e/knowledge/journeys/j1-cold-start.e2e.test.ts b/packages/commands/tests/e2e/knowledge/journeys/j1-cold-start.e2e.test.ts
new file mode 100644
index 00000000..a43c9dde
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/j1-cold-start.e2e.test.ts
@@ -0,0 +1,202 @@
+// J1 cold-start first answer: from zero to the first citable answer.
+// upload → kb create --wait → retrieve recalls the marker → service create (search/chat, draft)
+// → search --agent-version beta recalls → chat --agent-version beta first answer.
+// Closure assertions: the fixture marker is recalled by retrieve/search (hard);
+// the chat answer cites the marker (soft).
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson } from "../../helpers.ts";
+import { JOURNEY_J1_ROUTES } from "../../topic-routes.ts";
+import {
+  cleanupKbFixture,
+  createJourneyReporter,
+  createKbWithDocs,
+  nodesRecallMarker,
+  patchSearchServiceRetrievalConfig,
+  pollUntil,
+  uniqueMarker,
+  type KbFixture,
+} from "./journey-helpers.ts";
+
+describe.skipIf(!isKbAdminE2EReady())("journey J1: 冷启动首答 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("upload → create → retrieve → search(beta) → chat(beta) 回路闭合", async () => {
+    const reporter = createJourneyReporter(import.meta.url);
+    const marker = uniqueMarker("j1");
+    const fixture: Partial<KbFixture> = {};
+    const serviceAgentIds: string[] = [];
+    try {
+      // 1) Upload + create the knowledge base (--wait for the initial import)
+      const kb = await createKbWithDocs(reporter, JOURNEY_J1_ROUTES, "j1", [marker], workspaceId);
+      Object.assign(fixture, kb);
+
+      // 2) retrieve directly against the base recalls the marker (hard assertion,
+      // polling to absorb index-visibility lag)
+      // Gotcha: retrieve is a legacy DashScope-host command and does not accept --workspace-id
+      const retrievePoll = await pollUntil(
+        () =>
+          reporter.runStep("retrieve marker", JOURNEY_J1_ROUTES, [
+            "knowledge",
+            "retrieve",
+            "--index-id",
+            kb.indexId,
+            "--query",
+            marker,
+            "--output",
+            "json",
+          ]),
+        (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+        { timeoutMs: 180_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`retrieve 轮询 ${retrievePoll.attempts} 次`);
+      expect(retrievePoll.satisfied, `retrieve 未召回标记词 ${marker}`).toBe(true);
+
+      // 3) Create a retrieval service (initial draft/beta); search on the draft recalls (hard assertion)
+      const searchServiceRun = await reporter.runStep(
+        "service create (search)",
+        JOURNEY_J1_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "create",
+          "--name",
+          `e2e-j1-s-${Date.now() % 100000000}`,
+          "--scene",
+          "search",
+          "--index-id",
+          kb.indexId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ],
+      );
+      expect(searchServiceRun.exitCode, searchServiceRun.stderr).toBe(0);
+      const searchAgentId = searchServiceRun.stdout.trim().split("\n").pop()!;
+      expect(searchAgentId).toMatch(/^aid-/);
+      reporter.trackResource("service", searchAgentId);
+      serviceAgentIds.push(searchAgentId);
+
+      // Server gotcha: a minimally created search service is missing required
+      // retrieval parameters — backfill before calling (see journey-helpers)
+      await patchSearchServiceRetrievalConfig(
+        reporter,
+        JOURNEY_J1_ROUTES,
+        searchAgentId,
+        workspaceId,
+      );
+
+      const searchPoll = await pollUntil(
+        () =>
+          reporter.runStep("search marker (beta)", JOURNEY_J1_ROUTES, [
+            "knowledge",
+            "search",
+            "--query",
+            marker,
+            "--agent-id",
+            searchAgentId,
+            "--agent-version",
+            "beta",
+            "--workspace-id",
+            workspaceId,
+            "--output",
+            "json",
+          ]),
+        (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+        { timeoutMs: 120_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`search 轮询 ${searchPoll.attempts} 次`);
+      expect(searchPoll.satisfied, `search(beta) 未召回标记词 ${marker}`).toBe(true);
+
+      // 4) Create a chat service; first answer on the draft (non-empty answer is a
+      // hard assertion; citing the marker is a soft assertion for manual review)
+      const chatServiceRun = await reporter.runStep("service create (chat)", JOURNEY_J1_ROUTES, [
+        "knowledge",
+        "service",
+        "create",
+        "--name",
+        `e2e-j1-c-${Date.now() % 100000000}`,
+        "--scene",
+        "chat",
+        "--index-id",
+        kb.indexId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(chatServiceRun.exitCode, chatServiceRun.stderr).toBe(0);
+      const chatAgentId = chatServiceRun.stdout.trim().split("\n").pop()!;
+      expect(chatAgentId).toMatch(/^aid-/);
+      reporter.trackResource("service", chatAgentId);
+      serviceAgentIds.push(chatAgentId);
+
+      const chatRun = await reporter.runStep("chat first answer (beta)", JOURNEY_J1_ROUTES, [
+        "knowledge",
+        "chat",
+        "--message",
+        `What is ${marker}? Answer strictly based on the knowledge base.`,
+        "--agent-id",
+        chatAgentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(chatRun.exitCode, chatRun.stderr).toBe(0);
+      const chatData = parseStdoutJson<{ answer?: string }>(chatRun.stdout);
+      const answerText = chatData.answer?.trim() ?? "";
+      expect(answerText.length, "chat 回答为空").toBeGreaterThan(0);
+      reporter.recordSoft(
+        "chat 回答引用 fixture 标记词",
+        answerText.includes(marker),
+        answerText || "(empty)",
+      );
+
+      // 5) Negative branch: calling a version number that was never published —
+      // the server rejects (HTTP 400, verified live) and the CLI exits non-zero
+      // with the error passed through (the version set is server-side state)
+      const chatBadVersionRun = await reporter.runStep(
+        "chat unpublished version (expect reject)",
+        JOURNEY_J1_ROUTES,
+        [
+          "knowledge",
+          "chat",
+          "--message",
+          `What is ${marker}?`,
+          "--agent-id",
+          chatAgentId,
+          "--agent-version",
+          "999",
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(chatBadVersionRun.exitCode, "未发布版本号应被服务端拒绝").not.toBe(0);
+      expect(chatBadVersionRun.stderr).toMatch(/HTTP 400/);
+    } finally {
+      for (const agentId of serviceAgentIds) {
+        const deleteRun = await reporter.runStep(
+          `cleanup: service delete ${agentId}`,
+          JOURNEY_J1_ROUTES,
+          [
+            "knowledge",
+            "service",
+            "delete",
+            "--agent-id",
+            agentId,
+            "--yes",
+            "--workspace-id",
+            workspaceId,
+          ],
+        );
+        if (deleteRun.exitCode === 0) reporter.markCleaned(agentId);
+      }
+      await cleanupKbFixture(reporter, JOURNEY_J1_ROUTES, fixture, workspaceId);
+      reporter.finalize();
+    }
+    // Observed create times vary widely plus three polling phases — timeout sized for the worst path
+  }, 900_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/journeys/j2-content-ops.e2e.test.ts b/packages/commands/tests/e2e/knowledge/journeys/j2-content-ops.e2e.test.ts
new file mode 100644
index 00000000..6e1f114a
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/j2-content-ops.e2e.test.ts
@@ -0,0 +1,224 @@
+// J2 content operations: routine document add/remove and the visibility loop.
+// create (doc1+doc2) → doc list/status checks → doc tag → retrieve hits both markers
+// → doc delete doc2 → retrieve verifies markerB is gone and markerA remains.
+// Note: there is no "append documents to an existing base" command (kb update takes
+// no doc-id), so incremental semantics are expressed as a two-document create + deleting one.
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson } from "../../helpers.ts";
+import { JOURNEY_J2_ROUTES } from "../../topic-routes.ts";
+import {
+  cleanupKbFixture,
+  createJourneyReporter,
+  createKbWithDocs,
+  nodesRecallMarker,
+  pollUntil,
+  uniqueMarker,
+  type KbFixture,
+} from "./journey-helpers.ts";
+
+describe.skipIf(!isKbAdminE2EReady())("journey J2: 内容运维 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("建库(双文档) → list/status/tag → 删除其一 → 召回可见性闭环", async () => {
+    const reporter = createJourneyReporter(import.meta.url);
+    const markerA = uniqueMarker("j2a");
+    const markerB = uniqueMarker("j2b");
+    const fixture: Partial<KbFixture> = {};
+    try {
+      // 1) Create the base with two documents
+      const kb = await createKbWithDocs(
+        reporter,
+        JOURNEY_J2_ROUTES,
+        "j2",
+        [markerA, markerB],
+        workspaceId,
+      );
+      Object.assign(fixture, kb);
+      const [fileIdA, fileIdB] = kb.fileIds as [string, string];
+
+      // 2) doc list contains both documents (hard); doc status terminal state COMPLETED (hard)
+      const docListRun = await reporter.runStep("doc list", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "doc",
+        "list",
+        "--index-id",
+        kb.indexId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(docListRun.exitCode, docListRun.stderr).toBe(0);
+      const listedDocIds = docListRun.stdout.trim().split("\n");
+      expect(listedDocIds).toContain(fileIdA);
+      expect(listedDocIds).toContain(fileIdB);
+
+      const docStatusRun = await reporter.runStep("doc status", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "doc",
+        "status",
+        "--index-id",
+        kb.indexId,
+        "--job-id",
+        kb.jobId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(docStatusRun.exitCode, docStatusRun.stderr).toBe(0);
+      expect(docStatusRun.stdout.trim()).toBe("COMPLETED");
+
+      // 2.1) Negative branch: querying a job id that does not exist on this base —
+      // the server error (Index.IndexJobNotExist, verified live) passes through
+      // verbatim with a non-zero exit
+      const badJobStatusRun = await reporter.runStep(
+        "doc status unknown job (expect reject)",
+        JOURNEY_J2_ROUTES,
+        [
+          "knowledge",
+          "doc",
+          "status",
+          "--index-id",
+          kb.indexId,
+          "--job-id",
+          "job_nonexistent_e2e",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(badJobStatusRun.exitCode, "不存在的 job id 应被服务端拒绝").not.toBe(0);
+      expect(badJobStatusRun.stderr).toMatch(/not exist/i);
+
+      // 2.5) knowledge stats — monitor endpoint returns valid structure (hard)
+      const statsRun = await reporter.runStep("kb stats", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "stats",
+        "--index-id",
+        kb.indexId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(statsRun.exitCode, statsRun.stderr).toBe(0);
+      const statsData = parseStdoutJson<{
+        data?: {
+          storageMonitorData?: { indexStorageLimit?: number };
+          qpsMonitorData?: { monitorData?: unknown[] };
+        };
+      }>(statsRun.stdout);
+      expect(typeof statsData.data?.storageMonitorData?.indexStorageLimit).toBe("number");
+      expect(Array.isArray(statsData.data?.qpsMonitorData?.monitorData)).toBe(true);
+      reporter.recordNote(
+        `storage limit=${statsData.data?.storageMonitorData?.indexStorageLimit} qps windows=${statsData.data?.qpsMonitorData?.monitorData?.length ?? 0}`,
+      );
+
+      // 3) doc tag on doc2 (tagging succeeds: hard; tag read-back: soft — server-side
+      // display lag or the API not echoing tags are both tolerable)
+      const tagValue = `e2e-j2-${Date.now() % 100000000}`;
+      const docTagRun = await reporter.runStep("doc tag doc2", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "doc",
+        "tag",
+        "--doc-id",
+        fileIdB,
+        "--tag",
+        tagValue,
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(docTagRun.exitCode, docTagRun.stderr).toBe(0);
+      const tagReadbackRun = await reporter.runStep("doc list (tag readback)", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "doc",
+        "list",
+        "--index-id",
+        kb.indexId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      reporter.recordSoft(
+        "doc list 回读可见新标签",
+        tagReadbackRun.exitCode === 0 && tagReadbackRun.stdout.includes(tagValue),
+        `tag=${tagValue} exit=${tagReadbackRun.exitCode}`,
+      );
+
+      // 4) retrieve hits both markers (hard, polling to absorb indexing lag)
+      // Gotcha: retrieve is a legacy DashScope-host command and does not accept --workspace-id
+      const retrieveMarker = (marker: string, stepName: string) =>
+        pollUntil(
+          () =>
+            reporter.runStep(stepName, JOURNEY_J2_ROUTES, [
+              "knowledge",
+              "retrieve",
+              "--index-id",
+              kb.indexId,
+              "--query",
+              marker,
+              "--output",
+              "json",
+            ]),
+          (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+          { timeoutMs: 180_000, intervalMs: 15_000 },
+        );
+      const pollA = await retrieveMarker(markerA, "retrieve markerA");
+      expect(pollA.satisfied, `retrieve 未召回 ${markerA}`).toBe(true);
+      const pollB = await retrieveMarker(markerB, "retrieve markerB");
+      expect(pollB.satisfied, `retrieve 未召回 ${markerB}`).toBe(true);
+
+      // 5) Delete doc2 → markerB no longer recalled while markerA remains (hard)
+      const docDeleteRun = await reporter.runStep("doc delete doc2", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "doc",
+        "delete",
+        "--index-id",
+        kb.indexId,
+        "--doc-id",
+        fileIdB,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(docDeleteRun.exitCode, docDeleteRun.stderr).toBe(0);
+
+      const goneB = await pollUntil(
+        () =>
+          reporter.runStep("retrieve markerB (expect miss)", JOURNEY_J2_ROUTES, [
+            "knowledge",
+            "retrieve",
+            "--index-id",
+            kb.indexId,
+            "--query",
+            markerB,
+            "--output",
+            "json",
+          ]),
+        (run) => run.exitCode === 0 && !run.stdout.includes(markerB),
+        { timeoutMs: 180_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`doc delete 后 markerB 消失轮询 ${goneB.attempts} 次`);
+      expect(goneB.satisfied, `doc delete 后 ${markerB} 仍可召回`).toBe(true);
+
+      const stillA = await reporter.runStep("retrieve markerA (still hit)", JOURNEY_J2_ROUTES, [
+        "knowledge",
+        "retrieve",
+        "--index-id",
+        kb.indexId,
+        "--query",
+        markerA,
+        "--output",
+        "json",
+      ]);
+      expect(stillA.exitCode, stillA.stderr).toBe(0);
+      expect(
+        nodesRecallMarker(stillA.stdout, markerA),
+        `doc delete 误伤: ${markerA} 不再召回`,
+      ).toBe(true);
+    } finally {
+      await cleanupKbFixture(reporter, JOURNEY_J2_ROUTES, fixture, workspaceId);
+      reporter.finalize();
+    }
+    // Base creation plus several polling phases — timeout sized for the worst path
+  }, 900_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/journeys/j3-chunk-tuning.e2e.test.ts b/packages/commands/tests/e2e/knowledge/journeys/j3-chunk-tuning.e2e.test.ts
new file mode 100644
index 00000000..aa3da198
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/j3-chunk-tuning.e2e.test.ts
@@ -0,0 +1,200 @@
+// J3 retrieval tuning: the real effect of chunk-level exclusion on recall.
+// create → chunk list locates the marker chunk → chunk update --exclude → retrieve
+// asserts the exclusion flag (hard) → chunk update --include restores → retrieve
+// asserts restoration (soft, index-refresh lag is tolerable).
+// Semantic gotcha (verified live): the legacy retrieve endpoint does not filter
+// excluded chunks; it only sets metadata.is_displayed_chunk_content to false —
+// that flag is the closure signal.
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson } from "../../helpers.ts";
+import { JOURNEY_J3_ROUTES } from "../../topic-routes.ts";
+import {
+  cleanupKbFixture,
+  createJourneyReporter,
+  createKbWithDocs,
+  nodesRecallMarker,
+  pollUntil,
+  uniqueMarker,
+  type KbFixture,
+} from "./journey-helpers.ts";
+
+interface ChunkListResponse {
+  data?: {
+    nodes?: Array<{
+      text?: string;
+      metadata?: { _id?: string; doc_id?: string; content?: string };
+    }>;
+  };
+}
+
+interface RetrieveResponse {
+  data?: {
+    nodes?: Array<{
+      text?: string;
+      metadata?: { content?: string; is_displayed_chunk_content?: boolean };
+    }>;
+  };
+}
+
+/** Exclusion flag of the node containing the marker; undefined when the marker is not found */
+function markerNodeDisplayFlag(stdout: string, marker: string): boolean | undefined {
+  let response: RetrieveResponse;
+  try {
+    response = parseStdoutJson<RetrieveResponse>(stdout);
+  } catch {
+    return undefined;
+  }
+  const markedNode = (response.data?.nodes ?? []).find((node) =>
+    (node.metadata?.content ?? node.text ?? "").includes(marker),
+  );
+  if (!markedNode) return undefined;
+  return markedNode.metadata?.is_displayed_chunk_content !== false;
+}
+
+describe.skipIf(!isKbAdminE2EReady())("journey J3: 检索精修 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("chunk exclude → 排除标志生效 → include 恢复", async () => {
+    const reporter = createJourneyReporter(import.meta.url);
+    const marker = uniqueMarker("j3");
+    const fixture: Partial<KbFixture> = {};
+    try {
+      // 1) Create the base and confirm the marker is recallable (baseline for judging exclude)
+      const kb = await createKbWithDocs(reporter, JOURNEY_J3_ROUTES, "j3", [marker], workspaceId);
+      Object.assign(fixture, kb);
+
+      // Gotcha: retrieve is a legacy DashScope-host command and does not accept --workspace-id
+      const retrieveArgs = [
+        "knowledge",
+        "retrieve",
+        "--index-id",
+        kb.indexId,
+        "--query",
+        marker,
+        "--output",
+        "json",
+      ];
+      const baseline = await pollUntil(
+        () => reporter.runStep("retrieve baseline", JOURNEY_J3_ROUTES, retrieveArgs),
+        (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+        { timeoutMs: 180_000, intervalMs: 15_000 },
+      );
+      expect(baseline.satisfied, `基线未召回标记词 ${marker}`).toBe(true);
+
+      // 2) chunk list locates the chunk containing the marker (metadata._id / doc_id feed update)
+      const chunkListRun = await reporter.runStep("chunk list", JOURNEY_J3_ROUTES, [
+        "knowledge",
+        "chunk",
+        "list",
+        "--index-id",
+        kb.indexId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(chunkListRun.exitCode, chunkListRun.stderr).toBe(0);
+      const chunkData = parseStdoutJson<ChunkListResponse>(chunkListRun.stdout);
+      const markedNode = (chunkData.data?.nodes ?? []).find((node) =>
+        (node.metadata?.content ?? node.text ?? "").includes(marker),
+      );
+      expect(markedNode, `chunk list 中未找到含 ${marker} 的切片`).toBeTruthy();
+      const chunkId = markedNode!.metadata?._id ?? "";
+      const chunkDocId = markedNode!.metadata?.doc_id ?? "";
+      expect(chunkId).toBeTruthy();
+      expect(chunkDocId).toBeTruthy();
+      reporter.recordNote(`目标 chunk=${chunkId} doc=${chunkDocId}`);
+
+      // 3) exclude → the exclusion flag takes effect on the marker node (hard)
+      const excludeRun = await reporter.runStep("chunk update --exclude", JOURNEY_J3_ROUTES, [
+        "knowledge",
+        "chunk",
+        "update",
+        "--index-id",
+        kb.indexId,
+        "--chunk-id",
+        chunkId,
+        "--doc-id",
+        chunkDocId,
+        "--exclude",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(excludeRun.exitCode, excludeRun.stderr).toBe(0);
+
+      const excluded = await pollUntil(
+        () => reporter.runStep("retrieve after exclude", JOURNEY_J3_ROUTES, retrieveArgs),
+        (run) => run.exitCode === 0 && markerNodeDisplayFlag(run.stdout, marker) === false,
+        { timeoutMs: 180_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`exclude 生效轮询 ${excluded.attempts} 次`);
+      expect(excluded.satisfied, `exclude 后 ${marker} 所在 chunk 未标记为排除`).toBe(true);
+
+      // 4) include restores → exclusion flag cleared (soft: index-refresh lag on the
+      // restore path varies a lot; result goes to the report for manual review)
+      const includeRun = await reporter.runStep("chunk update --include", JOURNEY_J3_ROUTES, [
+        "knowledge",
+        "chunk",
+        "update",
+        "--index-id",
+        kb.indexId,
+        "--chunk-id",
+        chunkId,
+        "--doc-id",
+        chunkDocId,
+        "--include",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(includeRun.exitCode, includeRun.stderr).toBe(0);
+
+      const restored = await pollUntil(
+        () => reporter.runStep("retrieve after include", JOURNEY_J3_ROUTES, retrieveArgs),
+        (run) => run.exitCode === 0 && markerNodeDisplayFlag(run.stdout, marker) === true,
+        { timeoutMs: 120_000, intervalMs: 15_000 },
+      );
+      reporter.recordSoft(
+        "include 恢复后排除标志解除",
+        restored.satisfied,
+        `attempts=${restored.attempts} exit=${restored.value.exitCode}`,
+      );
+
+      // 5) Negative branch: deleting a chunk id that does not exist on this base —
+      // the server rejects (Index.InvalidParameter, verified live) and the error
+      // passes through verbatim; the marker chunk must remain recallable afterwards
+      const badDeleteRun = await reporter.runStep(
+        "chunk delete unknown id (expect reject)",
+        JOURNEY_J3_ROUTES,
+        [
+          "knowledge",
+          "chunk",
+          "delete",
+          "--index-id",
+          kb.indexId,
+          "--chunk-id",
+          "chunk_nonexistent_e2e_0000",
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(badDeleteRun.exitCode, "不存在的 chunk id 应被服务端拒绝").not.toBe(0);
+      expect(badDeleteRun.stderr).toMatch(/invalid|not exist/i);
+
+      const afterBadDelete = await reporter.runStep(
+        "retrieve after failed delete",
+        JOURNEY_J3_ROUTES,
+        retrieveArgs,
+      );
+      expect(afterBadDelete.exitCode, afterBadDelete.stderr).toBe(0);
+      expect(
+        nodesRecallMarker(afterBadDelete.stdout, marker),
+        `失败的删除误伤: ${marker} 不再召回`,
+      ).toBe(true);
+    } finally {
+      await cleanupKbFixture(reporter, JOURNEY_J3_ROUTES, fixture, workspaceId);
+      reporter.finalize();
+    }
+    // Base creation plus three polling phases — timeout sized for the worst path
+  }, 900_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/journeys/j4-service-tuning.e2e.test.ts b/packages/commands/tests/e2e/knowledge/journeys/j4-service-tuning.e2e.test.ts
new file mode 100644
index 00000000..2b299fc0
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/j4-service-tuning.e2e.test.ts
@@ -0,0 +1,326 @@
+// J4 service tuning: draft (beta) usable → config change persisted → released version carries the change after deploy.
+// create + service create (search, initial draft/beta) → search --agent-version beta recalls (hard)
+// → service update --description/--temperature (scalar merge path) → get (beta) asserts (hard)
+// → service update --config-file tweaking kb_search_configs (whole-replace path) → get (beta) asserts
+//   the nested change AND that the replace kept the scalar tuning (hard) → deploy
+// → get (released version) asserts both changes landed in the published version (hard) → released search recalls (hard).
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson } from "../../helpers.ts";
+import { JOURNEY_J4_ROUTES } from "../../topic-routes.ts";
+import {
+  cleanupKbFixture,
+  createJourneyReporter,
+  createKbWithDocs,
+  nodesRecallMarker,
+  patchSearchServiceRetrievalConfig,
+  pollUntil,
+  uniqueMarker,
+  type KbFixture,
+} from "./journey-helpers.ts";
+
+describe.skipIf(!isKbAdminE2EReady())("journey J4: 问答服务调优 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("draft 可用 → update 落库 → deploy → 正式版详情携带修改且可用", async () => {
+    const reporter = createJourneyReporter(import.meta.url);
+    const marker = uniqueMarker("j4");
+    const fixture: Partial<KbFixture> = {};
+    let agentId = "";
+    try {
+      // 1) Create the base + a retrieval service bound to it (initial draft/beta)
+      const kb = await createKbWithDocs(reporter, JOURNEY_J4_ROUTES, "j4", [marker], workspaceId);
+      Object.assign(fixture, kb);
+
+      const createServiceRun = await reporter.runStep(
+        "service create (search)",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "create",
+          "--name",
+          `e2e-j4-${Date.now() % 100000000}`,
+          "--scene",
+          "search",
+          "--index-id",
+          kb.indexId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ],
+      );
+      expect(createServiceRun.exitCode, createServiceRun.stderr).toBe(0);
+      agentId = createServiceRun.stdout.trim().split("\n").pop()!;
+      expect(agentId).toMatch(/^aid-/);
+      reporter.trackResource("service", agentId);
+
+      // Server gotcha: a minimally created search service is missing required
+      // retrieval parameters — backfill before calling (see journey-helpers)
+      await patchSearchServiceRetrievalConfig(reporter, JOURNEY_J4_ROUTES, agentId, workspaceId);
+
+      // 2) Draft search recalls (hard, polling to absorb index/service propagation lag)
+      const betaSearchArgs = [
+        "knowledge",
+        "search",
+        "--query",
+        marker,
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ];
+      const betaPoll = await pollUntil(
+        () => reporter.runStep("search (beta)", JOURNEY_J4_ROUTES, betaSearchArgs),
+        (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+        { timeoutMs: 180_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`beta search 轮询 ${betaPoll.attempts} 次`);
+      expect(betaPoll.satisfied, `search(beta) 未召回标记词 ${marker}`).toBe(true);
+
+      // 3) tune the draft: description (top-level) + temperature (config-level scalar,
+      //    read-merge-write keeps the backfilled retrieval params) → get asserts both (hard)
+      const newDescription = `journey j4 tuned at ${Date.now()}`;
+      const tunedTemperature = 0.55;
+      const updateRun = await reporter.runStep(
+        "service update --description --temperature",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "update",
+          "--agent-id",
+          agentId,
+          "--description",
+          newDescription,
+          "--temperature",
+          String(tunedTemperature),
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(updateRun.exitCode, updateRun.stderr).toBe(0);
+
+      const getRun = await reporter.runStep("service get (beta)", JOURNEY_J4_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(getRun.exitCode, getRun.stderr).toBe(0);
+      const getData = parseStdoutJson<{
+        data?: {
+          agent_desc?: string;
+          agent_details?: Array<{
+            agent_config?: { temperature?: number } & Record<string, unknown>;
+          }>;
+        };
+      }>(getRun.stdout);
+      expect(getData.data?.agent_desc).toBe(newDescription);
+      expect(getData.data?.agent_details?.[0]?.agent_config?.temperature).toBe(tunedTemperature);
+
+      // 3.5) complex nested tuning via --config-file (whole-replace path, distinct
+      //      from the scalar merge path above): read the current beta config, tweak
+      //      kb_search_configs, write it back — then assert the nested change landed
+      //      AND the replace kept the scalar tuning intact
+      const tunedDenseTopK = 66; // distinctive value, still recall-safe (loose top-k)
+      const betaConfig = getData.data?.agent_details?.[0]?.agent_config as
+        | ({ kb_search_configs?: Array<Record<string, unknown>> } & Record<string, unknown>)
+        | undefined;
+      expect(betaConfig?.kb_search_configs?.length, "beta 配置应含 kb_search_configs").toBeTruthy();
+      for (const kbConfig of betaConfig!.kb_search_configs!) {
+        kbConfig.dense_similarity_top_k = tunedDenseTopK;
+      }
+      const configDir = mkdtempSync(join(tmpdir(), "j4-config-"));
+      const configFile = join(configDir, "agent-config.json");
+      writeFileSync(configFile, JSON.stringify(betaConfig));
+      const configUpdateRun = await reporter.runStep(
+        "service update --config-file (kb_search_configs)",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "update",
+          "--agent-id",
+          agentId,
+          "--config-file",
+          configFile,
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(configUpdateRun.exitCode, configUpdateRun.stderr).toBe(0);
+
+      const betaAfterConfigRun = await reporter.runStep(
+        "service get (beta, after config-file)",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "get",
+          "--agent-id",
+          agentId,
+          "--agent-version",
+          "beta",
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(betaAfterConfigRun.exitCode, betaAfterConfigRun.stderr).toBe(0);
+      const betaAfterConfig = parseStdoutJson<{
+        data?: {
+          agent_details?: Array<{
+            agent_config?: {
+              temperature?: number;
+              kb_search_configs?: Array<{ dense_similarity_top_k?: number }>;
+            };
+          }>;
+        };
+      }>(betaAfterConfigRun.stdout).data?.agent_details?.[0]?.agent_config;
+      expect(
+        betaAfterConfig?.kb_search_configs?.[0]?.dense_similarity_top_k,
+        "kb_search_configs 嵌套修改未落库",
+      ).toBe(tunedDenseTopK);
+      expect(betaAfterConfig?.temperature, "config-file 整体替换不应冲掉已调优的 temperature").toBe(
+        tunedTemperature,
+      );
+
+      // 4) deploy → the published version's detail must carry the tuned config (hard):
+      //    search alone only proves the released service responds, not that the
+      //    change actually shipped
+      const deployRun = await reporter.runStep("service deploy", JOURNEY_J4_ROUTES, [
+        "knowledge",
+        "service",
+        "deploy",
+        "--agent-id",
+        agentId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(deployRun.exitCode, deployRun.stderr).toBe(0);
+      const deployedVersion = deployRun.stdout.trim().split("\n").pop() ?? "";
+      expect(deployedVersion, "deploy 应输出新版本号").toBeTruthy();
+      reporter.recordNote(`deploy 版本号: ${deployedVersion}`);
+
+      const releasedGetRun = await reporter.runStep(
+        `service get (released v${deployedVersion})`,
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "service",
+          "get",
+          "--agent-id",
+          agentId,
+          "--agent-version",
+          deployedVersion,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(releasedGetRun.exitCode, releasedGetRun.stderr).toBe(0);
+      const releasedData = parseStdoutJson<{
+        data?: {
+          agent_details?: Array<{
+            agent_version?: string;
+            agent_config?: {
+              temperature?: number;
+              kb_search_configs?: Array<{ dense_similarity_top_k?: number }>;
+            };
+          }>;
+        };
+      }>(releasedGetRun.stdout);
+      const releasedDetail = releasedData.data?.agent_details?.find(
+        (detail) => detail.agent_version === deployedVersion,
+      );
+      expect(releasedDetail, `get 应返回已发布版本 ${deployedVersion} 的详情`).toBeTruthy();
+      expect(releasedDetail?.agent_config?.temperature, "调优的 temperature 未进入正式版配置").toBe(
+        tunedTemperature,
+      );
+      expect(
+        releasedDetail?.agent_config?.kb_search_configs?.[0]?.dense_similarity_top_k,
+        "调优的 kb_search_configs 未进入正式版配置",
+      ).toBe(tunedDenseTopK);
+
+      // 5) released search (without --agent-version) recalls (hard)
+      const releasedPoll = await pollUntil(
+        () =>
+          reporter.runStep("search (released)", JOURNEY_J4_ROUTES, [
+            "knowledge",
+            "search",
+            "--query",
+            marker,
+            "--agent-id",
+            agentId,
+            "--workspace-id",
+            workspaceId,
+            "--output",
+            "json",
+          ]),
+        (run) => run.exitCode === 0 && nodesRecallMarker(run.stdout, marker),
+        { timeoutMs: 120_000, intervalMs: 15_000 },
+      );
+      reporter.recordNote(`正式版 search 轮询 ${releasedPoll.attempts} 次`);
+      expect(releasedPoll.satisfied, `发布后正式版 search 未召回 ${marker}`).toBe(true);
+
+      // 6) Negative branch: calling a version number that was never published —
+      // the server rejects (RagAgentNotExist, verified live) and the CLI exits
+      // non-zero with the error passed through (the version set is server-side state)
+      const badVersionSearchRun = await reporter.runStep(
+        "search unpublished version (expect reject)",
+        JOURNEY_J4_ROUTES,
+        [
+          "knowledge",
+          "search",
+          "--query",
+          marker,
+          "--agent-id",
+          agentId,
+          "--agent-version",
+          "999",
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ],
+      );
+      expect(badVersionSearchRun.exitCode, "未发布版本号应被服务端拒绝").not.toBe(0);
+      expect(badVersionSearchRun.stderr).toMatch(/Agent application not found|RagAgentNotExist/i);
+    } finally {
+      if (agentId) {
+        const deleteRun = await reporter.runStep("cleanup: service delete", JOURNEY_J4_ROUTES, [
+          "knowledge",
+          "service",
+          "delete",
+          "--agent-id",
+          agentId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        if (deleteRun.exitCode === 0) reporter.markCleaned(agentId);
+      }
+      await cleanupKbFixture(reporter, JOURNEY_J4_ROUTES, fixture, workspaceId);
+      reporter.finalize();
+    }
+    // Base creation plus two polling phases plus deploy — timeout sized for the worst path
+  }, 900_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/journeys/j5-data-plane.e2e.test.ts b/packages/commands/tests/e2e/knowledge/journeys/j5-data-plane.e2e.test.ts
new file mode 100644
index 00000000..6f03e6e3
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/j5-data-plane.e2e.test.ts
@@ -0,0 +1,206 @@
+// J5 data-plane governance: the collection/category/file read-write loop (decoupled from the index plane).
+// collection reuse-or-create (no delete API, fixed-name idempotent) → category add → visible in list
+// → upload a file into the self-created category → file list/get → file delete
+// → category delete → list verifies removal.
+// gating: collection artifacts cannot be cleaned up — only enable explicitly for a
+// full manual regression (BAILIAN_E2E_CONNECTOR=1).
+import { describe, expect, test } from "vite-plus/test";
+import { isConnectorE2EReady, parseStdoutJson } from "../../helpers.ts";
+import { JOURNEY_J5_ROUTES } from "../../topic-routes.ts";
+import { createJourneyReporter, uniqueMarker, writeMarkerFixture } from "./journey-helpers.ts";
+
+describe.skipIf(!isConnectorE2EReady())("journey J5: 数据面治理 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("collection → category → file 读写 → 类目清理闭环", async () => {
+    const reporter = createJourneyReporter(import.meta.url);
+    let categoryId = "";
+    let categoryName = "";
+    try {
+      // 1) collection reuse-or-create (fixed-name idempotent — avoid accumulating undeletable collections)
+      // Server rejects names longer than 20 characters ("Connector name is longer than 20")
+      const collectionName = "e2e-journey-coll";
+      const collectionGetRun = await reporter.runStep("collection get by name", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "collection",
+        "get",
+        "--name",
+        collectionName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      let collectionId = collectionGetRun.exitCode === 0 ? collectionGetRun.stdout.trim() : "";
+      if (!collectionId) {
+        const collectionCreateRun = await reporter.runStep("collection create", JOURNEY_J5_ROUTES, [
+          "knowledge",
+          "collection",
+          "create",
+          "--name",
+          collectionName,
+          "--description",
+          "journey J5 fixture collection (PLATFORM, reused across runs)",
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(collectionCreateRun.exitCode, collectionCreateRun.stderr).toBe(0);
+        collectionId = collectionCreateRun.stdout.trim();
+      }
+      expect(collectionId).toBeTruthy();
+      reporter.trackResource("collection", collectionId, { persistent: true });
+
+      // 2) Self-created category → visible via exact-name filtering in list (hard)
+      categoryName = `e2e-j5-${Date.now() % 100000000}`;
+      const categoryAddRun = await reporter.runStep("category add", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "category",
+        "add",
+        "--name",
+        categoryName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(categoryAddRun.exitCode, categoryAddRun.stderr).toBe(0);
+      categoryId = categoryAddRun.stdout.trim();
+      expect(categoryId).toMatch(/^cate_/);
+      reporter.trackResource("category", categoryId);
+
+      const categoryListRun = await reporter.runStep("category list (filter)", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--name",
+        categoryName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(categoryListRun.exitCode, categoryListRun.stderr).toBe(0);
+      expect(categoryListRun.stdout.trim().split("\n")).toContain(categoryId);
+
+      // 3) Upload a file into the self-created category → file list/get → file delete
+      // (only touch self-created artifacts)
+      const marker = uniqueMarker("j5");
+      const filePath = writeMarkerFixture("j5", marker);
+      const uploadRun = await reporter.runStep("doc upload to category", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "doc",
+        "upload",
+        "--file",
+        filePath,
+        "--category-id",
+        categoryId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+      const fileId = uploadRun.stdout.trim();
+      expect(fileId).toMatch(/^file_/);
+      reporter.trackResource("data-center-file", fileId);
+
+      const fileListRun = await reporter.runStep("file list", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "file",
+        "list",
+        "--category-id",
+        categoryId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(fileListRun.exitCode, fileListRun.stderr).toBe(0);
+      expect(fileListRun.stdout.trim().split("\n")).toContain(fileId);
+
+      const fileGetRun = await reporter.runStep("file get", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "file",
+        "get",
+        "--file-id",
+        fileId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(fileGetRun.exitCode, fileGetRun.stderr).toBe(0);
+      const fileDetail = parseStdoutJson<{ data?: { category?: string } }>(fileGetRun.stdout);
+      expect(fileDetail.data?.category).toBe(categoryId);
+
+      const fileDeleteRun = await reporter.runStep("file delete", JOURNEY_J5_ROUTES, [
+        "knowledge",
+        "file",
+        "delete",
+        "--file-id",
+        fileId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
+      reporter.markCleaned(fileId);
+
+      // 3.1) Negative branch: deleting the same file again — it no longer exists,
+      // so the server rejects ("Cant find out file", verified live) and the error
+      // passes through verbatim with a non-zero exit
+      const repeatDeleteRun = await reporter.runStep(
+        "file delete again (expect reject)",
+        JOURNEY_J5_ROUTES,
+        [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ],
+      );
+      expect(repeatDeleteRun.exitCode, "重复删除已不存在的文件应被服务端拒绝").not.toBe(0);
+      expect(repeatDeleteRun.stderr).toMatch(/cant find|InvalidParameter/i);
+    } finally {
+      if (categoryId) {
+        // 4) Clean up the self-created category + list verifies removal
+        // (doubles as live coverage of category delete)
+        const categoryDeleteRun = await reporter.runStep(
+          "cleanup: category delete",
+          JOURNEY_J5_ROUTES,
+          [
+            "knowledge",
+            "category",
+            "delete",
+            "--category-id",
+            categoryId,
+            "--yes",
+            "--workspace-id",
+            workspaceId,
+          ],
+        );
+        if (categoryDeleteRun.exitCode === 0) {
+          reporter.markCleaned(categoryId);
+          const goneListRun = await reporter.runStep(
+            "category list (verify gone)",
+            JOURNEY_J5_ROUTES,
+            [
+              "knowledge",
+              "category",
+              "list",
+              "--name",
+              categoryName,
+              "--workspace-id",
+              workspaceId,
+              "--quiet",
+            ],
+          );
+          if (goneListRun.exitCode === 0) {
+            expect(goneListRun.stdout.trim().split("\n")).not.toContain(categoryId);
+          }
+        }
+      }
+      reporter.finalize();
+    }
+  }, 300_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts b/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts
new file mode 100644
index 00000000..192b4107
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/journeys/journey-helpers.ts
@@ -0,0 +1,474 @@
+// Shared journey-level infrastructure: marker-word fixtures, eventual-consistency
+// polling, IndexStatusError retrying deletes, and an on-disk reporter (per-step
+// stdout/stderr, soft assertions, resource inventory, human-readable report).
+import { appendFileSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  e2eLabelFromMetaUrl,
+  makeE2eOutputDir,
+  parseStdoutJson,
+  runCommandE2e,
+  type RunCliResult,
+} from "../../helpers.ts";
+import type { E2eRouteExports } from "../../topic-routes.ts";
+
+// ---- Marker words and fixtures ----
+
+/** Unique marker word: journey closure is judged by whether it can be recalled */
+export function uniqueMarker(journeyId: string): string {
+  return `E2E_MARKER_${journeyId.toUpperCase()}_${Date.now()}_${Math.floor(Math.random() * 10000)}`;
+}
+
+/** Write a temporary md fixture containing the marker word; returns the file path */
+export function writeMarkerFixture(journeyId: string, marker: string): string {
+  const fixtureDir = mkdtempSync(join(tmpdir(), `journey-${journeyId}-`));
+  const filePath = join(fixtureDir, `${journeyId}-${Date.now()}.md`);
+  writeFileSync(
+    filePath,
+    [
+      `# Journey fixture for ${journeyId}`,
+      "",
+      `The secret code word of this document is ${marker}.`,
+      `${marker} is a fictional internal project name used only by CLI journey tests.`,
+      `When asked about ${marker}, this document is the authoritative source.`,
+      "",
+    ].join("\n"),
+  );
+  return filePath;
+}
+
+// ---- Eventual-consistency polling ----
+
+export interface PollOutcome<T> {
+  value: T;
+  satisfied: boolean;
+  attempts: number;
+}
+
+export async function sleep(milliseconds: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+/**
+ * Poll until the predicate holds or the timeout is reached. Never throws —
+ * returns satisfied and lets the caller decide hard vs soft assertion.
+ */
+export async function pollUntil<T>(
+  action: () => Promise<T>,
+  predicate: (value: T) => boolean,
+  options: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<PollOutcome<T>> {
+  const timeoutMs = options.timeoutMs ?? 120_000;
+  const intervalMs = options.intervalMs ?? 10_000;
+  const deadline = Date.now() + timeoutMs;
+  let attempts = 0;
+  let value = await action();
+  attempts += 1;
+  while (!predicate(value) && Date.now() < deadline) {
+    await sleep(intervalMs);
+    value = await action();
+    attempts += 1;
+  }
+  return { value, satisfied: predicate(value), attempts };
+}
+
+// ---- Delete with IndexStatusError retry (server gotcha: briefly undeletable right after import) ----
+
+export async function deleteKbWithRetry(
+  runner: (args: string[]) => Promise<RunCliResult>,
+  indexId: string,
+  workspaceId: string,
+): Promise<RunCliResult> {
+  const args = [
+    "knowledge",
+    "delete",
+    "--index-id",
+    indexId,
+    "--yes",
+    "--workspace-id",
+    workspaceId,
+  ];
+  let deleteRun = await runner(args);
+  for (let retry = 0; retry < 5 && deleteRun.exitCode !== 0; retry++) {
+    if (!deleteRun.stderr.includes("IndexStatusError")) break; // other errors are not retried
+    await sleep(10_000);
+    deleteRun = await runner(args);
+  }
+  return deleteRun;
+}
+
+// ---- Journey reporter: artifacts for manual review ----
+
+interface JourneyStepRecord {
+  index: number;
+  name: string;
+  args: string[];
+  exitCode: number | null;
+  durationMs: number;
+  stdoutFile: string;
+  stderrFile: string;
+}
+
+interface SoftAssertionRecord {
+  name: string;
+  passed: boolean;
+  detail: string;
+}
+
+interface TrackedResource {
+  type: string;
+  id: string;
+  cleaned: boolean;
+  /** Resources expected to persist (e.g. no delete API); excluded from the uncleaned warning */
+  persistent: boolean;
+}
+
+export interface JourneyReporter {
+  outputDir: string;
+  runStep(
+    name: string,
+    routes: E2eRouteExports,
+    args: string[],
+    envOverrides?: NodeJS.ProcessEnv,
+  ): Promise<RunCliResult>;
+  recordSoft(name: string, passed: boolean, detail: string): void;
+  recordNote(text: string): void;
+  trackResource(type: string, id: string, options?: { persistent?: boolean }): void;
+  markCleaned(id: string): void;
+  /** Inventory of uncleaned resources (queryable before finalize, for afterAll fallbacks) */
+  uncleanedResources(): TrackedResource[];
+  finalize(): void;
+}
+
+function sanitizeStepName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 60);
+}
+
+export function createJourneyReporter(metaUrl: string): JourneyReporter {
+  const outputDir = makeE2eOutputDir(e2eLabelFromMetaUrl(metaUrl));
+  const logFile = join(outputDir, "journey.log");
+  const steps: JourneyStepRecord[] = [];
+  const softAssertions: SoftAssertionRecord[] = [];
+  const notes: string[] = [];
+  const resources: TrackedResource[] = [];
+
+  function appendLog(line: string): void {
+    appendFileSync(logFile, `${new Date().toISOString()} ${line}\n`);
+  }
+
+  function flushResources(): void {
+    writeFileSync(join(outputDir, "resources.json"), `${JSON.stringify(resources, null, 2)}\n`);
+  }
+
+  return {
+    outputDir,
+
+    async runStep(name, routes, args, envOverrides = {}) {
+      const index = steps.length + 1;
+      const prefix = `${String(index).padStart(2, "0")}-${sanitizeStepName(name)}`;
+      const startedAt = Date.now();
+      // Redaction convention: only CLI args are persisted (credentials travel via
+      // env/config, never in args); env is not persisted
+      const result = await runCommandE2e(routes, args, envOverrides);
+      const durationMs = Date.now() - startedAt;
+      const stdoutFile = `${prefix}.stdout.txt`;
+      const stderrFile = `${prefix}.stderr.txt`;
+      writeFileSync(join(outputDir, stdoutFile), result.stdout);
+      writeFileSync(join(outputDir, stderrFile), result.stderr);
+      steps.push({
+        index,
+        name,
+        args,
+        exitCode: result.exitCode,
+        durationMs,
+        stdoutFile,
+        stderrFile,
+      });
+      appendLog(`[${prefix}] exit=${result.exitCode} ${durationMs}ms args: ${args.join(" ")}`);
+      return result;
+    },
+
+    recordSoft(name, passed, detail) {
+      softAssertions.push({ name, passed, detail });
+      appendLog(`[soft] ${passed ? "PASS" : "MISS"} ${name}`);
+    },
+
+    recordNote(text) {
+      notes.push(text);
+      appendLog(`[note] ${text}`);
+    },
+
+    trackResource(type, id, options = {}) {
+      resources.push({ type, id, cleaned: false, persistent: options.persistent ?? false });
+      flushResources();
+    },
+
+    markCleaned(id) {
+      const resource = resources.find((candidate) => candidate.id === id && !candidate.cleaned);
+      if (resource) resource.cleaned = true;
+      flushResources();
+    },
+
+    uncleanedResources() {
+      return resources.filter((resource) => !resource.cleaned && !resource.persistent);
+    },
+
+    finalize() {
+      flushResources();
+      const leaked = resources.filter((resource) => !resource.cleaned && !resource.persistent);
+      const lines: string[] = [
+        `# Journey report`,
+        "",
+        `- generated: ${new Date().toISOString()}`,
+        `- output dir: ${outputDir}`,
+        "",
+        "## Steps",
+        "",
+        "| # | step | exit | duration | stdout |",
+        "| --- | --- | --- | --- | --- |",
+        ...steps.map(
+          (step) =>
+            `| ${step.index} | ${step.name} | ${step.exitCode} | ${step.durationMs}ms | ${step.stdoutFile} |`,
+        ),
+        "",
+        "## Soft assertions (manual review)",
+        "",
+      ];
+      if (softAssertions.length === 0) {
+        lines.push("(none)");
+      } else {
+        for (const softAssertion of softAssertions) {
+          lines.push(
+            `### ${softAssertion.passed ? "✅" : "⚠️"} ${softAssertion.name}`,
+            "",
+            "```",
+            softAssertion.detail,
+            "```",
+            "",
+          );
+        }
+      }
+      lines.push("", "## Notes", "");
+      lines.push(...(notes.length === 0 ? ["(none)"] : notes.map((note) => `- ${note}`)));
+      lines.push("", "## Resources", "");
+      lines.push("| type | id | cleaned |", "| --- | --- | --- |");
+      lines.push(
+        ...resources.map(
+          (resource) =>
+            `| ${resource.type} | ${resource.id} | ${resource.persistent ? "retained (persistent)" : String(resource.cleaned)} |`,
+        ),
+      );
+      if (leaked.length > 0) {
+        lines.push(
+          "",
+          "## ⚠️ Uncleaned resources (manual cleanup required)",
+          "",
+          ...leaked.map((resource) => `- ${resource.type}: ${resource.id}`),
+        );
+      }
+      lines.push("");
+      writeFileSync(join(outputDir, "journey-report.md"), lines.join("\n"));
+      appendLog(
+        `[finalize] steps=${steps.length} soft=${softAssertions.length} leaked=${leaked.length}`,
+      );
+    },
+  };
+}
+
+// ---- Shared J1–J4 setup: upload marker documents + create a knowledge base ----
+
+export interface KbFixture {
+  indexId: string;
+  jobId: string;
+  fileIds: string[];
+}
+
+/**
+ * Upload N marker documents and run `kb create --wait`. Any failure throws
+ * (message includes stderr). Artifacts (data-center file / kb) are tracked via
+ * trackResource; cleanup is the caller's responsibility.
+ */
+export async function createKbWithDocs(
+  reporter: JourneyReporter,
+  routes: E2eRouteExports,
+  journeyId: string,
+  markers: string[],
+  workspaceId: string,
+): Promise<KbFixture> {
+  const fileIds: string[] = [];
+  for (const [markerIndex, marker] of markers.entries()) {
+    const filePath = writeMarkerFixture(journeyId, marker);
+    const uploadRun = await reporter.runStep(`upload doc ${markerIndex + 1}`, routes, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      filePath,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    if (uploadRun.exitCode !== 0) {
+      throw new Error(`doc upload failed (marker ${marker}): ${uploadRun.stderr}`);
+    }
+    const fileId = uploadRun.stdout.trim();
+    reporter.trackResource("data-center-file", fileId);
+    fileIds.push(fileId);
+  }
+
+  const kbName = `e2e-${journeyId}-${Date.now() % 100000000}`;
+  const createRun = await reporter.runStep("kb create --wait", routes, [
+    "knowledge",
+    "create",
+    "--name",
+    kbName,
+    ...fileIds.flatMap((fileId) => ["--doc-id", fileId]),
+    "--workspace-id",
+    workspaceId,
+    "--wait",
+    "--output",
+    "json",
+  ]);
+  if (createRun.exitCode !== 0) {
+    throw new Error(`kb create failed: ${createRun.stderr}`);
+  }
+  const createData = parseStdoutJson<{
+    data?: { pipelineId?: string; ingestionId?: string };
+    final_status?: string;
+  }>(createRun.stdout);
+  const indexId = createData.data?.pipelineId ?? "";
+  const jobId = createData.data?.ingestionId ?? "";
+  if (!indexId) throw new Error(`kb create returned no pipelineId: ${createRun.stdout}`);
+  reporter.trackResource("kb", indexId);
+  reporter.recordNote(
+    `kb ${indexId} (${kbName}) import final_status=${createData.final_status ?? "?"}`,
+  );
+  return { indexId, jobId, fileIds };
+}
+
+/** Unified cleanup: kb delete (with retry) + data-center file delete. Never throws — failures surface in the report. */
+export async function cleanupKbFixture(
+  reporter: JourneyReporter,
+  routes: E2eRouteExports,
+  fixture: Partial<KbFixture>,
+  workspaceId: string,
+): Promise<void> {
+  if (fixture.indexId) {
+    const deleteRun = await deleteKbWithRetry(
+      (args) => reporter.runStep("cleanup: kb delete", routes, args),
+      fixture.indexId,
+      workspaceId,
+    );
+    if (deleteRun.exitCode === 0) reporter.markCleaned(fixture.indexId);
+  }
+  for (const fileId of fixture.fileIds ?? []) {
+    const fileDeleteRun = await reporter.runStep(`cleanup: file delete ${fileId}`, routes, [
+      "knowledge",
+      "file",
+      "delete",
+      "--file-id",
+      fileId,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    if (fileDeleteRun.exitCode === 0) reporter.markCleaned(fileId);
+  }
+}
+
+// ---- Marker-recall predicate (strict) ----
+
+/**
+ * Positive recall check for retrieve/search JSON output: the marker must appear
+ * inside a returned node's text (not merely anywhere in the raw output — doc_name
+ * or other metadata echoing the marker must not count as recall).
+ * Negative assertions ("marker gone") should keep scanning the whole stdout:
+ * absence from the entire output is the stronger guarantee.
+ */
+export function nodesRecallMarker(stdout: string, marker: string): boolean {
+  try {
+    const payload = JSON.parse(stdout) as {
+      data?: { nodes?: Array<{ text?: string; metadata?: { content?: string } }> };
+    };
+    return (payload.data?.nodes ?? []).some((node) =>
+      (node.metadata?.content ?? node.text ?? "").includes(marker),
+    );
+  } catch {
+    // Mid-poll runs may fail before emitting JSON — treat as "not recalled yet"
+    return false;
+  }
+}
+
+// ---- Backfill required retrieval parameters for search services (server gotcha) ----
+// The minimal kb_search_configs created by service create --index-id is missing
+// required fields like rerank_min_score / dense_similarity_top_k, so the search
+// endpoint rejects it (InvalidParameter). The chat scene is unaffected.
+// Workaround: get the beta config → backfill the fields → update --config-file.
+
+interface AgentGetPayload {
+  data?: {
+    agent_details?: Array<{
+      agent_config?: { kb_search_configs?: Array<Record<string, unknown>> } & Record<
+        string,
+        unknown
+      >;
+    }>;
+  };
+}
+
+export async function patchSearchServiceRetrievalConfig(
+  reporter: JourneyReporter,
+  routes: E2eRouteExports,
+  agentId: string,
+  workspaceId: string,
+): Promise<void> {
+  const getRun = await reporter.runStep("service get (patch retrieval config)", routes, [
+    "knowledge",
+    "service",
+    "get",
+    "--agent-id",
+    agentId,
+    "--agent-version",
+    "beta",
+    "--workspace-id",
+    workspaceId,
+    "--output",
+    "json",
+  ]);
+  if (getRun.exitCode !== 0) {
+    throw new Error(`service get failed while patching retrieval config: ${getRun.stderr}`);
+  }
+  const agentConfig = parseStdoutJson<AgentGetPayload>(getRun.stdout).data?.agent_details?.[0]
+    ?.agent_config;
+  if (!agentConfig) throw new Error(`service get returned no agent_config: ${getRun.stdout}`);
+  for (const kbConfig of agentConfig.kb_search_configs ?? []) {
+    Object.assign(kbConfig, {
+      rerank_min_score: 0.01,
+      dense_similarity_top_k: 100,
+      sparse_similarity_top_k: 50,
+      enable_reranking: true,
+      rerank_top_n: 5,
+    });
+  }
+  const configDir = mkdtempSync(join(tmpdir(), "journey-svc-cfg-"));
+  const configFile = join(configDir, "agent-config.json");
+  writeFileSync(configFile, JSON.stringify(agentConfig));
+  const updateRun = await reporter.runStep("service update (patch retrieval config)", routes, [
+    "knowledge",
+    "service",
+    "update",
+    "--agent-id",
+    agentId,
+    "--config-file",
+    configFile,
+    "--workspace-id",
+    workspaceId,
+  ]);
+  if (updateRun.exitCode !== 0) {
+    throw new Error(`service update failed while patching retrieval config: ${updateRun.stderr}`);
+  }
+  reporter.recordNote(
+    `service ${agentId} kb_search_configs patched with required retrieval parameters`,
+  );
+}
diff --git a/packages/commands/tests/e2e/knowledge-chat.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-chat.e2e.test.ts
similarity index 72%
rename from packages/commands/tests/e2e/knowledge-chat.e2e.test.ts
rename to packages/commands/tests/e2e/knowledge/knowledge-chat.e2e.test.ts
index 5ee66f56..9d09f7ad 100644
--- a/packages/commands/tests/e2e/knowledge-chat.e2e.test.ts
+++ b/packages/commands/tests/e2e/knowledge/knowledge-chat.e2e.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, test } from "vite-plus/test";
-import { isChatE2EReady, parseStdoutJson, runCommandE2e } from "./helpers.ts";
-import { KNOWLEDGE_CHAT_ROUTES } from "./topic-routes.ts";
+import {
+  isChatE2EReady,
+  isMultimodalChatE2EReady,
+  parseStdoutJson,
+  runCommandE2e,
+} from "../helpers.ts";
+import { KNOWLEDGE_CHAT_ROUTES } from "../topic-routes.ts";
 
 interface ContentPart {
   type: string;
@@ -17,6 +22,7 @@ interface DryRunBody {
     parameters?: {
       agent_options?: {
         agent_id?: string;
+        agent_version?: string;
       };
     };
     stream?: boolean;
@@ -61,7 +67,7 @@ describe("e2e: knowledge chat", () => {
   test("缺少 --workspace-id 时非零退出并提示", async () => {
     const { stderr, exitCode } = await runCommandE2e(
       KNOWLEDGE_CHAT_ROUTES,
-      // 假 key + 隔离配置目录:避免本机 config 的 workspace_id/api_key 漏入
+      // Fake key + isolated config dir: keep the local config's workspace_id/api_key from leaking in
       [
         "knowledge",
         "chat",
@@ -101,6 +107,29 @@ describe("e2e: knowledge chat", () => {
     expect(data.request?.input?.messages?.[0]?.role).toBe("user");
     expect(data.request?.input?.messages?.[0]?.content).toBe("什么是RAG");
     expect(data.request?.parameters?.agent_options?.agent_id).toBe("aid_test");
+    // Without --agent-version the field is not sent (default behavior unchanged)
+    expect(data.request?.parameters?.agent_options).not.toHaveProperty("agent_version");
+  });
+
+  test("--dry-run + --agent-version 落在 agent_options 内", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHAT_ROUTES, [
+      "knowledge",
+      "chat",
+      "--dry-run",
+      "--message",
+      "什么是RAG",
+      "--agent-id",
+      "aid_test",
+      "--agent-version",
+      "2",
+      "--workspace-id",
+      "ws_test",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.parameters?.agent_options?.agent_version).toBe("2");
   });
 
   test("--dry-run 多轮消息解析 role:content 前缀", async () => {
@@ -193,6 +222,47 @@ describe("e2e: knowledge chat", () => {
       image_url: { url: "https://example.com/b.png" },
     });
   });
+
+  test("--dry-run JSON 对象消息通道解析结构化 content", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHAT_ROUTES, [
+      "knowledge",
+      "chat",
+      "--dry-run",
+      "--message",
+      '{"role":"user","content":[{"type":"text","text":"结构化消息"}]}',
+      "--agent-id",
+      "aid_test",
+      "--workspace-id",
+      "ws_test",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    const firstMsg = data.request?.input?.messages?.[0];
+    expect(firstMsg?.role).toBe("user");
+    expect(Array.isArray(firstMsg?.content)).toBe(true);
+    const parts = firstMsg?.content as ContentPart[];
+    expect(parts[0]).toEqual({ type: "text", text: "结构化消息" });
+  });
+
+  test("--image 与消息内嵌 image_url 冲突报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHAT_ROUTES, [
+      "knowledge",
+      "chat",
+      "--dry-run",
+      "--message",
+      '{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://example.com/e.png"}}]}',
+      "--image",
+      "https://example.com/x.png",
+      "--agent-id",
+      "aid_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/embedded/i);
+  });
 });
 
 interface ChatJsonResult {
@@ -324,3 +394,34 @@ describe.skipIf(!isChatE2EReady())("e2e: knowledge chat (live)", () => {
     expect(stderr).toBeTruthy();
   });
 });
+
+// Long-lived console-created fixture (multimodal Q&A services cannot be created
+// via the CLI — see .env BAILIAN_E2E_IMAGE_CHAT_AGENT_ID)
+describe.skipIf(!isMultimodalChatE2EReady())(
+  "e2e: knowledge chat --image live (常驻 fixture)",
+  () => {
+    const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+    const imageChatAgentId = process.env.BAILIAN_E2E_IMAGE_CHAT_AGENT_ID!;
+
+    test("多模态问答接受 --image 并返回非空回答", async () => {
+      const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHAT_ROUTES, [
+        "knowledge",
+        "chat",
+        "--message",
+        "图里有什么",
+        "--image",
+        "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg",
+        "--agent-id",
+        imageChatAgentId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<ChatJsonResult>(stdout);
+      expect(data.answer).toBeTruthy();
+      expect(data.answer.length).toBeGreaterThan(0);
+    }, 120_000);
+  },
+);
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts
new file mode 100644
index 00000000..fc00111d
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-chunk-category-file.e2e.test.ts
@@ -0,0 +1,2308 @@
+// chunk / stats / category / file / collection / import-oss commands: the static
+// group covers help/missing-args/dry-run gotchas per command; the live group runs
+// the full chunk chain (add → list → update → delete) plus category/file read-write chains.
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import {
+  isImageKbE2EReady,
+  isKbAdminE2EReady,
+  isOssImportE2EReady,
+  isTableKbE2EReady,
+  parseStdoutJson,
+  runCommandE2e,
+} from "../helpers.ts";
+import {
+  KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES,
+  KNOWLEDGE_KB_DELETE_ROUTES,
+} from "../topic-routes.ts";
+import { deleteKbWithRetry, pollUntil } from "./journeys/journey-helpers.ts";
+
+interface DryRunBody {
+  endpoint?: string;
+  request?: Record<string, unknown>;
+}
+
+const COMMON = ["--workspace-id", "ws_test", "--dry-run", "--output", "json"];
+
+// --help smoke across all commands in this group: [command path, representative flag expected in help]
+const HELP_SMOKE_CASES: Array<[string[], RegExp]> = [
+  [["knowledge", "chunk", "list"], /--doc-id/i],
+  [["knowledge", "chunk", "update"], /--exclude/i],
+  [["knowledge", "chunk", "delete"], /--chunk-id/i],
+  [["knowledge", "stats"], /--start/i],
+  [["knowledge", "category", "list"], /--next-token/i],
+  [["knowledge", "category", "add"], /--parent-id/i],
+  [["knowledge", "category", "delete"], /--category-id/i],
+  [["knowledge", "file", "list"], /--category-id/i],
+  [["knowledge", "file", "get"], /--file-id/i],
+  [["knowledge", "file", "delete"], /--yes/i],
+  [["knowledge", "collection", "create"], /--store-type/i],
+  [["knowledge", "collection", "get"], /--collection-id/i],
+  [["knowledge", "doc", "import-oss"], /--oss-key/i],
+];
+
+describe("e2e: chunk/category/file 全命令 --help 冒烟", () => {
+  test("12 条命令 help 退出 0 且展示代表性 flag（chunk add 单独测）", async () => {
+    for (const [commandPath, flagPattern] of HELP_SMOKE_CASES) {
+      const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        ...commandPath,
+        "--help",
+      ]);
+      expect(exitCode, `${commandPath.join(" ")}: ${stderr}`).toBe(0);
+      expect(stderr, commandPath.join(" ")).toMatch(flagPattern);
+    }
+  }, 60_000);
+});
+
+describe("e2e: knowledge chunk 组 (静态)", () => {
+  test("chunk add: --help 展示双通道 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--content/i);
+    expect(stderr).toMatch(/--field/i);
+    expect(stderr).toMatch(/--image-url/i);
+  });
+
+  test("chunk add: --content 与 --field 同传 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content",
+      "hello",
+      "--field",
+      "colA=1",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: --field 无 = 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--field",
+      "novalue",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: 无任何内容 flag 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--content|--field/);
+  });
+
+  test("chunk add: --content 与 --content-file 同传 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content",
+      "hello",
+      "--content-file",
+      "/tmp/whatever.md",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: --content 6001 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content",
+      "x".repeat(6001),
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: --title 51 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content",
+      "hello",
+      "--title",
+      "x".repeat(51),
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: 11 个 --image-url 报 USAGE (2)", async () => {
+    const imageUrlArgs = Array.from({ length: 11 }, (_, urlIndex) => [
+      "--image-url",
+      `https://example.com/img${urlIndex}.png`,
+    ]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      ...imageUrlArgs,
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk add: dry-run 断言 pipelineId + field 键值原样", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--field",
+      "列A=v=1",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/chunk\/create/);
+    expect(data.request?.pipelineId).toBe("idx_test");
+    const fieldMap = data.request?.field as Record<string, string> | undefined;
+    expect(fieldMap?.["列A"]).toBe("v=1");
+  });
+
+  test("chunk add: --content-file 读文件并映射为 field.content", async () => {
+    const contentDir = mkdtempSync(join(tmpdir(), "chunk-add-cf-"));
+    const contentPath = join(contentDir, "chunk.md");
+    writeFileSync(contentPath, "content-file channel fixture body");
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content-file",
+      contentPath,
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    const fieldMap = data.request?.field as Record<string, unknown> | undefined;
+    expect(fieldMap?.content).toBe("content-file channel fixture body");
+  });
+
+  test("chunk add: dry-run 断言 title/image_urls 键名映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      "idx_test",
+      "--content",
+      "hello",
+      "--title",
+      "intro",
+      "--image-url",
+      "https://example.com/a.png",
+      "--image-url",
+      "https://example.com/b.png",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    const fieldMap = data.request?.field as Record<string, unknown> | undefined;
+    expect(fieldMap?.title).toBe("intro");
+    // Gotcha: the request key is image_urls (snake, plural), not imageUrl
+    expect(fieldMap?.image_urls).toEqual([
+      "https://example.com/a.png",
+      "https://example.com/b.png",
+    ]);
+    expect(fieldMap).not.toHaveProperty("imageUrl");
+  });
+
+  test("chunk list: dry-run 断言 pageNum/pageSize 键名 (camelCase 坑位)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "list",
+      "--index-id",
+      "idx_test",
+      "--page-number",
+      "2",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.pageNum).toBe(2);
+    expect(data.request?.indexId).toBe("idx_test");
+    expect(data.request).not.toHaveProperty("page_num");
+  });
+
+  test("chunk list: --page-size 101 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "list",
+      "--index-id",
+      "idx_test",
+      "--page-size",
+      "101",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: content 9 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--content",
+      "123456789",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: --content-file 内容 9 字符 dry-run 预演报 USAGE (2)", async () => {
+    // Rehearsal semantics: dry-run reads the file and enforces the 10-6000 range
+    const contentDir = mkdtempSync(join(tmpdir(), "chunk-upd-cf-"));
+    const contentPath = join(contentDir, "short.txt");
+    writeFileSync(contentPath, "123456789");
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--content-file",
+      contentPath,
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: 无修改项 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/nothing to update/i);
+  });
+
+  test("chunk update: --content 与 --content-file 同传 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--content",
+      "corrected content text",
+      "--content-file",
+      "/tmp/whatever.md",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: --title 51 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--title",
+      "x".repeat(51),
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: --exclude 与 --include 互斥 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--exclude",
+      "--include",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("chunk update: dry-run 断言 isDisplayedChunkContent 缺省 true", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--doc-id",
+      "file_test",
+      "--content",
+      "corrected content text",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.pipelineId).toBe("idx_test");
+    expect(data.request?.isDisplayedChunkContent).toBe(true);
+  });
+
+  test("chunk delete: dry-run 12 个 id 分 2 批", async () => {
+    const chunkIdArgs = Array.from({ length: 12 }, (_, chunkIndex) => [
+      "--chunk-id",
+      `chunk_${chunkIndex}`,
+    ]).flat();
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "delete",
+      "--index-id",
+      "idx_test",
+      ...chunkIdArgs,
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ batches: Array<{ request: { chunkIds: string[] } }> }>(stdout);
+    expect(data.batches).toHaveLength(2);
+    expect(data.batches[0]!.request.chunkIds).toHaveLength(10);
+    expect(data.batches[1]!.request.chunkIds).toHaveLength(2);
+  });
+
+  test("chunk delete: 非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--chunk-id",
+      "chunk_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+});
+
+describe("e2e: kb stats / category / file / connector / import-oss (静态)", () => {
+  test("kb stats: dry-run 断言秒级字符串时间戳", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "stats",
+      "--index-id",
+      "idx_test",
+      "--start",
+      "2026-07-30T00:00:00Z",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/index\/monitor/);
+    expect(data.request?.startTimestamp).toBe("1785369600");
+    expect(typeof data.request?.endTimestamp).toBe("string");
+  });
+
+  test("kb stats: 13 位毫秒时间戳归一为秒", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "stats",
+      "--index-id",
+      "idx_test",
+      "--start",
+      "1785369600000",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.startTimestamp).toBe("1785369600");
+  });
+
+  test("kb stats: 非法时间报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "stats",
+      "--index-id",
+      "idx_test",
+      "--start",
+      "not-a-date",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("category list: dry-run 断言 type=UNSTRUCTURED 与 maxResult 单数键名", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "list",
+      "--max-result",
+      "5",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/listCategory/);
+    expect(data.request?.type).toBe("UNSTRUCTURED");
+    expect(data.request?.maxResult).toBe(5);
+    expect(data.request).not.toHaveProperty("maxResults");
+  });
+
+  test("category add: --name 21 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "add",
+      "--name",
+      "x".repeat(21),
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("category add: dry-run 断言 parentCategoryId/connectorId 键名映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "add",
+      "--name",
+      "sub-cate",
+      "--parent-id",
+      "cate_parent",
+      "--collection-id",
+      "conn_test",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/addCategory/);
+    expect(data.request?.categoryName).toBe("sub-cate");
+    expect(data.request?.categoryType).toBe("UNSTRUCTURED");
+    expect(data.request?.parentCategoryId).toBe("cate_parent");
+    expect(data.request?.connectorId).toBe("conn_test");
+  });
+
+  test("category delete: 非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "delete",
+      "--category-id",
+      "cate_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+
+  test("file list: 缺 --category-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "list",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("file list: dry-run 断言 fileIds 数组与 fileName/nextToken 键名透传", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "list",
+      "--category-id",
+      "cate_test",
+      "--name",
+      "report",
+      "--file-id",
+      "file_a",
+      "--file-id",
+      "file_b",
+      "--next-token",
+      "tok_1",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/listFile/);
+    expect(data.request?.fileIds).toEqual(["file_a", "file_b"]);
+    expect(data.request?.nextToken).toBe("tok_1");
+    // Gotcha: the filter key is fileName, not name
+    expect(data.request?.fileName).toBe("report");
+    expect(data.request).not.toHaveProperty("name");
+  });
+
+  test("file get: dry-run 断言 fileId", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "get",
+      "--file-id",
+      "file_test",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/describeFile/);
+    expect(data.request?.fileId).toBe("file_test");
+  });
+
+  test("file delete: 非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "delete",
+      "--file-id",
+      "file_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+
+  test("collection create: --name 21 字符 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "create",
+      "--name",
+      "x".repeat(21),
+      "--description",
+      "d",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("collection create: --store-type 非法值 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "create",
+      "--name",
+      "demo",
+      "--description",
+      "d",
+      "--store-type",
+      "oss",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("collection create: custom 缺 oss 参数 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "create",
+      "--name",
+      "demo",
+      "--description",
+      "d",
+      "--store-type",
+      "custom",
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("collection create: dry-run 断言 FILE + PLATFORM 缺省", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "create",
+      "--name",
+      "demo",
+      "--description",
+      "team docs",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.connectorType).toBe("FILE");
+    const connectorConfig = data.request?.fileConnectorConfig as { storeType?: string } | undefined;
+    expect(connectorConfig?.storeType).toBe("PLATFORM");
+  });
+
+  test("collection create: custom dry-run 断言 regionId/bucketName 键名映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "create",
+      "--name",
+      "oss-coll",
+      "--description",
+      "own bucket",
+      "--store-type",
+      "custom",
+      "--oss-region",
+      "cn-beijing",
+      "--oss-bucket",
+      "my-bucket",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    const connectorConfig = data.request?.fileConnectorConfig as
+      | { storeType?: string; regionId?: string; bucketName?: string }
+      | undefined;
+    expect(connectorConfig?.storeType).toBe("CUSTOM");
+    // CUSTOM fields are regionId/bucketName per add-connector.md — the earlier
+    // ossRegionId/ossBucket implementation was rejected live with InvalidParameter
+    expect(connectorConfig?.regionId).toBe("cn-beijing");
+    expect(connectorConfig?.bucketName).toBe("my-bucket");
+    expect(connectorConfig).not.toHaveProperty("ossRegionId");
+    expect(connectorConfig).not.toHaveProperty("ossBucket");
+  });
+
+  test("collection get: 都缺 / 都传 均 USAGE (2)", async () => {
+    const bothMissing = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "get",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(bothMissing.exitCode).toBe(2);
+    const bothGiven = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "get",
+      "--collection-id",
+      "conn_test",
+      "--name",
+      "demo",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(bothGiven.exitCode).toBe(2);
+  });
+
+  test("collection get: dry-run 断言 connectorName 键名", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "get",
+      "--name",
+      "my-conn",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/getConnector/);
+    expect(data.request?.connectorName).toBe("my-conn");
+    expect(data.request).not.toHaveProperty("connectorId");
+  });
+
+  test("doc import-oss: 缺 --bucket 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--region",
+      "cn-beijing",
+      "--oss-key",
+      "docs/a.pdf",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("doc import-oss: dry-run 断言 fileDetails 派生与 tag/overwrite/category 映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--bucket",
+      "my-bucket",
+      "--region",
+      "cn-beijing",
+      "--oss-key",
+      "docs/a.pdf",
+      "--category-id",
+      "cate_x",
+      "--tag",
+      "alpha",
+      "--overwrite",
+      ...COMMON,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/addFilesFromAuthorizedOss/);
+    expect(data.request?.categoryType).toBe("UNSTRUCTURED");
+    expect(data.request?.fileDetails).toEqual([{ fileName: "a.pdf", ossKey: "docs/a.pdf" }]);
+    expect(data.request?.categoryId).toBe("cate_x");
+    expect(data.request?.tags).toEqual(["alpha"]);
+    // Gotcha: the overwrite key is overWriteFileByOssKey (capital W)
+    expect(data.request?.overWriteFileByOssKey).toBe(true);
+  });
+
+  test("doc import-oss: 11 个 --tag 报 USAGE (2)", async () => {
+    const tagArgs = Array.from({ length: 11 }, (_, tagIndex) => ["--tag", `t${tagIndex}`]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--bucket",
+      "b",
+      "--region",
+      "cn-beijing",
+      "--oss-key",
+      "docs/a.pdf",
+      ...tagArgs,
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("doc import-oss: 11 个 oss-key 报 USAGE (2)", async () => {
+    const keyArgs = Array.from({ length: 11 }, (_, keyIndex) => [
+      "--oss-key",
+      `docs/f${keyIndex}.pdf`,
+    ]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--bucket",
+      "b",
+      "--region",
+      "cn-beijing",
+      ...keyArgs,
+      ...COMMON,
+    ]);
+    expect(exitCode).toBe(2);
+  });
+});
+
+describe.skipIf(!isKbAdminE2EReady())(
+  "e2e: chunk/category/file live (chunk 链路 + category/file 读)",
+  () => {
+    const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+    test("file get 不存在的 file-id: 服务端错误原样透传 (非零退出)", async () => {
+      const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "get",
+        "--file-id",
+        "file_nonexistent_e2e_0000",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(exitCode).not.toBe(0);
+      // Verified live: HTTP 200 + InvalidParameter with a "cant find" message
+      expect(stderr).toMatch(/cant find|InvalidParameter/i);
+    }, 60_000);
+
+    test("collection get/create live: 幂等复用固定名测试集合", async () => {
+      // collection has no delete API — reuse a fixed name idempotently instead of creating
+      // new ones (the legacy name e2e-test-connector is kept: that idempotent resource
+      // already exists server-side)
+      const connectorName = "e2e-test-connector";
+      const firstGetRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "collection",
+        "get",
+        "--name",
+        connectorName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      let connectorId = firstGetRun.exitCode === 0 ? firstGetRun.stdout.trim() : "";
+
+      if (!connectorId) {
+        const createRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "collection",
+          "create",
+          "--name",
+          connectorName,
+          "--description",
+          "e2e fixture connector (PLATFORM, reused across runs)",
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(createRun.exitCode, createRun.stderr).toBe(0);
+        connectorId = createRun.stdout.trim();
+      }
+      expect(connectorId).toBeTruthy();
+
+      // get by id asserts the detail fields
+      const getRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "collection",
+        "get",
+        "--collection-id",
+        connectorId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(getRun.exitCode, getRun.stderr).toBe(0);
+      const connectorDetail = parseStdoutJson<{
+        data: { connectorId?: string; connectorName?: string };
+      }>(getRun.stdout);
+      expect(connectorDetail.data.connectorId).toBe(connectorId);
+      expect(connectorDetail.data.connectorName).toBe(connectorName);
+    }, 60_000);
+
+    test("category list live: --max-result 1 触发 nextToken 游标翻页", async () => {
+      // Cursor pagination piggybacks on existing categories — no resources created
+      const firstPageRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--max-result",
+        "1",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(firstPageRun.exitCode, firstPageRun.stderr).toBe(0);
+      const firstPage = parseStdoutJson<{
+        data?: { nextToken?: string; categoryList?: Array<{ categoryId?: string }> };
+      }>(firstPageRun.stdout);
+      const firstCategoryId = firstPage.data?.categoryList?.[0]?.categoryId;
+      const nextToken = firstPage.data?.nextToken;
+      expect(firstCategoryId).toBeTruthy();
+      // A single-category workspace cannot paginate — nothing more to assert
+      if (!nextToken) return;
+
+      const secondPageRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--max-result",
+        "1",
+        "--next-token",
+        nextToken,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(secondPageRun.exitCode, secondPageRun.stderr).toBe(0);
+      const secondCategoryId = secondPageRun.stdout.trim().split("\n")[0];
+      expect(secondCategoryId).toBeTruthy();
+      expect(secondCategoryId).not.toBe(firstCategoryId);
+    }, 60_000);
+
+    test("隔离链路: category add → upload(--tag) → file list/get → 类目建库 → file delete → category delete", async () => {
+      // Test artifacts must live in (and be cleaned from) a self-created category;
+      // never touch existing data in the default category
+      const categoryName = `e2e-cate-${Date.now() % 100000000}`;
+      const categoryAddRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "add",
+        "--name",
+        categoryName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(categoryAddRun.exitCode, categoryAddRun.stderr).toBe(0);
+      const categoryId = categoryAddRun.stdout.trim();
+      expect(categoryId).toMatch(/^cate_/);
+
+      // category list asserts the new category is found via exact-name filtering
+      // (categoryName is an exact match — contract gotcha)
+      const categoryListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--name",
+        categoryName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(categoryListRun.exitCode, categoryListRun.stderr).toBe(0);
+      expect(categoryListRun.stdout.trim().split("\n")).toContain(categoryId);
+
+      try {
+        const fixtureDir = mkdtempSync(join(tmpdir(), "file-chain-e2e-"));
+        const filePath = join(fixtureDir, `fl-${Date.now()}.md`);
+        writeFileSync(filePath, "# file chain fixture\n");
+        const uploadRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "doc",
+          "upload",
+          "--file",
+          filePath,
+          "--category-id",
+          categoryId,
+          "--tag",
+          "e2e-upload-tag",
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+        const fileId = uploadRun.stdout.trim();
+
+        const fileListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "list",
+          "--category-id",
+          categoryId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(fileListRun.exitCode, fileListRun.stderr).toBe(0);
+        expect(fileListRun.stdout.trim().split("\n")).toContain(fileId);
+
+        const getRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "get",
+          "--file-id",
+          fileId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(getRun.exitCode, getRun.stderr).toBe(0);
+        const fileDetail = parseStdoutJson<{ data: { category?: string; tags?: unknown } }>(
+          getRun.stdout,
+        );
+        expect(fileDetail.data.category).toBe(categoryId);
+        // tags round-trip verifies the upload --tag → addFile tags mapping live
+        expect(JSON.stringify(fileDetail.data.tags ?? "")).toContain("e2e-upload-tag");
+
+        // kb create --category-id: the only live coverage of building a base from a
+        // category (all other chains use --doc-id); the base is throwaway
+        const kbCreateRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+          "knowledge",
+          "create",
+          "--name",
+          `e2e-cate-kb-${Date.now() % 100000000}`.slice(0, 20),
+          "--category-id",
+          categoryId,
+          "--workspace-id",
+          workspaceId,
+          "--wait",
+          "--quiet",
+        ]);
+        expect(kbCreateRun.exitCode, kbCreateRun.stderr).toBe(0);
+        const categoryKbId = kbCreateRun.stdout.trim().split("\n")[0]!;
+        expect(categoryKbId).toBeTruthy();
+        const kbDeleteRun = await deleteKbWithRetry(
+          (args) => runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, args),
+          categoryKbId,
+          workspaceId,
+        );
+        expect(kbDeleteRun.exitCode, kbDeleteRun.stderr).toBe(0);
+
+        // Delete only the exact fileId we just uploaded
+        const deleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+
+        // Verify the file is actually gone from the data center via read-back
+        const postFileListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "list",
+          "--category-id",
+          categoryId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(postFileListRun.exitCode, postFileListRun.stderr).toBe(0);
+        expect(postFileListRun.stdout.trim()).not.toContain(fileId);
+      } finally {
+        // Clean up the self-created category (doubles as live coverage of category delete)
+        const categoryDeleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "category",
+          "delete",
+          "--category-id",
+          categoryId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(categoryDeleteRun.exitCode, categoryDeleteRun.stderr).toBe(0);
+
+        // Verify the category is actually gone from the server via read-back
+        const postCategoryListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "category",
+          "list",
+          "--name",
+          categoryName,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(postCategoryListRun.exitCode, postCategoryListRun.stderr).toBe(0);
+        expect(postCategoryListRun.stdout.trim()).not.toContain(categoryId);
+      }
+      // kb create --wait adds a full import phase — generous timeout
+    }, 600_000);
+
+    test("chunk 全链路: 建库 → add → list 回读 → update → rerank 检索 → 分批 delete", async () => {
+      // Create a throwaway knowledge base (upload + create --wait, reusing existing commands)
+      const fixtureDir = mkdtempSync(join(tmpdir(), "chunk-chain-e2e-"));
+      const filePath = join(fixtureDir, `chunk-${Date.now()}.md`);
+      writeFileSync(filePath, "# chunk chain fixture: base document content\n");
+      const uploadRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "doc",
+        "upload",
+        "--file",
+        filePath,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+      const fileId = uploadRun.stdout.trim();
+
+      // Operating on an existing knowledge base would pollute it, and picking one from
+      // kb list is unreliable — the chunk add → list → update → delete chain needs the
+      // uploaded file in a base first, so create a throwaway base directly.
+      const createRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "create",
+        "--name",
+        `e2e-ck-${Date.now() % 100000000}`,
+        "--doc-id",
+        fileId,
+        "--workspace-id",
+        workspaceId,
+        "--wait",
+        "--quiet",
+      ]);
+      expect(createRun.exitCode, createRun.stderr).toBe(0);
+      const indexId = createRun.stdout.trim().split("\n")[0]!;
+
+      try {
+        // add
+        const addRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "add",
+          "--index-id",
+          indexId,
+          "--doc-id",
+          fileId,
+          "--content",
+          `e2e manual chunk content ${Date.now()}`,
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(addRun.exitCode, addRun.stderr).toBe(0);
+
+        // list read-back to grab chunk ids
+        const listRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(listRun.exitCode, listRun.stderr).toBe(0);
+        const chunkIds = listRun.stdout.trim().split("\n").filter(Boolean);
+        expect(chunkIds.length).toBeGreaterThan(0);
+        const targetChunkId = chunkIds[chunkIds.length - 1]!;
+
+        // update (change content)
+        const updateRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "update",
+          "--index-id",
+          indexId,
+          "--chunk-id",
+          targetChunkId,
+          "--doc-id",
+          fileId,
+          "--content",
+          "e2e updated chunk content",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(updateRun.exitCode, updateRun.stderr).toBe(0);
+
+        // Verify the content update landed on the server via independent read-back
+        const updateVerifyRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(updateVerifyRun.exitCode, updateVerifyRun.stderr).toBe(0);
+        const updateVerifyData = parseStdoutJson<{
+          data?: {
+            nodes?: Array<{ metadata?: { _id?: string; content?: string }; text?: string }>;
+          };
+        }>(updateVerifyRun.stdout);
+        const updatedChunk = updateVerifyData.data?.nodes?.find(
+          (node) => node.metadata?._id === targetChunkId,
+        );
+        expect(updatedChunk?.metadata?.content ?? updatedChunk?.text).toBe(
+          "e2e updated chunk content",
+        );
+
+        // update toggling --exclude only (no content — exercises the fetchChunkContent read-back path live)
+        const excludeRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "update",
+          "--index-id",
+          indexId,
+          "--chunk-id",
+          targetChunkId,
+          "--doc-id",
+          fileId,
+          "--exclude",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(excludeRun.exitCode, excludeRun.stderr).toBe(0);
+
+        // Verify the exclude flag landed on the server via independent read-back
+        const excludeVerifyRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(excludeVerifyRun.exitCode, excludeVerifyRun.stderr).toBe(0);
+        const excludeVerifyData = parseStdoutJson<{
+          data?: {
+            nodes?: Array<{ metadata?: { _id?: string; is_displayed_chunk_content?: boolean } }>;
+          };
+        }>(excludeVerifyRun.stdout);
+        const excludedChunk = excludeVerifyData.data?.nodes?.find(
+          (node) => node.metadata?._id === targetChunkId,
+        );
+        expect(excludedChunk?.metadata?.is_displayed_chunk_content).toBe(false);
+
+        // kb stats on this base doubles as live coverage of the monitor endpoint
+        // (the only indices endpoint not touched by the chain)
+        const statsRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "stats",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(statsRun.exitCode, statsRun.stderr).toBe(0);
+        const statsData = parseStdoutJson<{
+          data?: {
+            storageMonitorData?: { indexStorageLimit?: number };
+            qpsMonitorData?: { monitorData?: unknown[] };
+          };
+        }>(statsRun.stdout);
+        // Shape verified against the live API: the monitor fields are objects,
+        // not arrays as the public docs' empty-array examples suggest
+        expect(typeof statsData.data?.storageMonitorData?.indexStorageLimit).toBe("number");
+        expect(Array.isArray(statsData.data?.qpsMonitorData?.monitorData)).toBe(true);
+
+        // retrieve with full rerank params — the only live call of the rerank billing
+        // path (recall is not asserted: indexing lag would make it flaky; shape only)
+        const rerankRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "retrieve",
+          "--index-id",
+          indexId,
+          "--query",
+          "chunk chain fixture",
+          "--rerank",
+          "--rerank-model",
+          "qwen3-rerank-hybrid",
+          "--rerank-mode",
+          "similar",
+          "--rerank-top-n",
+          "5",
+          "--dense-similarity-top-k",
+          "20",
+          "--sparse-similarity-top-k",
+          "20",
+          "--output",
+          "json",
+        ]);
+        expect(rerankRun.exitCode, rerankRun.stderr).toBe(0);
+        const rerankData = parseStdoutJson<{ data?: { nodes?: unknown[] } }>(rerankRun.stdout);
+        expect(Array.isArray(rerankData.data?.nodes)).toBe(true);
+
+        // 10 more chunks force the >10-id auto-batching path in the live delete
+        // (sequential process spawns naturally respect the 10 req/s rate limit)
+        for (let extraIndex = 0; extraIndex < 10; extraIndex++) {
+          const extraAddRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+            "knowledge",
+            "chunk",
+            "add",
+            "--index-id",
+            indexId,
+            "--doc-id",
+            fileId,
+            "--content",
+            `e2e batch chunk content ${extraIndex}`,
+            "--workspace-id",
+            workspaceId,
+            "--quiet",
+          ]);
+          expect(extraAddRun.exitCode, extraAddRun.stderr).toBe(0);
+        }
+        const fullListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--page-size",
+          "100",
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(fullListRun.exitCode, fullListRun.stderr).toBe(0);
+        const allChunkIds = fullListRun.stdout.trim().split("\n").filter(Boolean);
+        expect(allChunkIds.length).toBeGreaterThan(10);
+
+        // batch delete all chunks — asserts the automatic split into multiple batches
+        const deleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "delete",
+          "--index-id",
+          indexId,
+          ...allChunkIds.flatMap((chunkId) => ["--chunk-id", chunkId]),
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+        expect(deleteRun.stdout).toMatch(
+          new RegExp(
+            `deleted: ${allChunkIds.length} chunk\\(s\\) in ${Math.ceil(allChunkIds.length / 10)} batch\\(es\\)`,
+          ),
+        );
+
+        // Verify the chunks are actually gone from the server via independent read-back
+        const postDeleteListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(postDeleteListRun.exitCode, postDeleteListRun.stderr).toBe(0);
+        expect(postDeleteListRun.stdout.trim()).toBe("");
+
+        // doc delete verifies document-level delete semantics (only unlinks from this
+        // base, unlike file delete). The --doc-id must be the full doc_id from doc
+        // list (e.g. "file_xxx_<workspaceId>"), NOT the bare fileId ("file_xxx") —
+        // passing the bare fileId returns Success but does not actually remove the
+        // document.
+        const preDocListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "doc",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(preDocListRun.exitCode, preDocListRun.stderr).toBe(0);
+        const preDocListData = parseStdoutJson<{
+          data?: { rows?: Array<{ doc_id?: string; doc_name?: string }> };
+        }>(preDocListRun.stdout);
+        const docRow = preDocListData.data?.rows?.find((row) => row.doc_id?.startsWith(fileId));
+        expect(
+          docRow,
+          `expected doc list to contain a doc_id starting with "${fileId}"`,
+        ).toBeTruthy();
+        const fullDocId = docRow!.doc_id!;
+
+        const docDeleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "doc",
+          "delete",
+          "--index-id",
+          indexId,
+          "--doc-id",
+          fullDocId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(docDeleteRun.exitCode, docDeleteRun.stderr).toBe(0);
+        expect(docDeleteRun.stdout).toMatch(new RegExp(fullDocId));
+
+        // Verify the document is actually gone from the server via independent read-back.
+        // doc delete is asynchronous — the server returns Success immediately but the
+        // document disappears from doc list after a propagation delay (same pattern as
+        // IndexStatusError on kb delete). Poll until the doc_id is gone or timeout.
+        let docGone = false;
+        for (let retry = 0; retry < 6; retry++) {
+          await new Promise((resolve) => setTimeout(resolve, 10_000));
+          const postDocListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+            "knowledge",
+            "doc",
+            "list",
+            "--index-id",
+            indexId,
+            "--workspace-id",
+            workspaceId,
+            "--quiet",
+          ]);
+          expect(postDocListRun.exitCode, postDocListRun.stderr).toBe(0);
+          if (!postDocListRun.stdout.trim().includes(fullDocId)) {
+            docGone = true;
+            break;
+          }
+        }
+        expect(
+          docGone,
+          `doc delete returned Success but the document is still in doc list after 60s`,
+        ).toBe(true);
+      } finally {
+        // Clean up the throwaway base + data-center file (same IndexStatusError retry as the kb delete chain)
+        await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        let cleanupRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+          "knowledge",
+          "delete",
+          "--index-id",
+          indexId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        for (let retry = 0; retry < 5 && cleanupRun.exitCode !== 0; retry++) {
+          if (!cleanupRun.stderr.includes("IndexStatusError")) break;
+          await new Promise((resolve) => setTimeout(resolve, 10_000));
+          cleanupRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+            "knowledge",
+            "delete",
+            "--index-id",
+            indexId,
+            "--yes",
+            "--workspace-id",
+            workspaceId,
+          ]);
+        }
+      }
+      // Observed duration varies widely (server-side parsing/indexing speed is unstable)
+      // — generous timeout to absorb the jitter
+    }, 600_000);
+  },
+);
+
+// Live parameter coverage: file-list 4 params + category-list 2 params +
+// chunk add/update --content-file + chunk list --doc-id. All in one self-cleaning
+// chain to minimize API calls.
+describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("file list(name/file-id/max-result/next-token) + category list(parent-id/collection-id) + chunk add/update --content-file + chunk list --doc-id", async () => {
+    // ── setup: create category → upload file ──
+    const categoryName = `e2e-param-${Date.now() % 100000000}`;
+    const categoryAddRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "add",
+      "--name",
+      categoryName,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(categoryAddRun.exitCode, categoryAddRun.stderr).toBe(0);
+    const categoryId = categoryAddRun.stdout.trim();
+    expect(categoryId).toMatch(/^cate_/);
+
+    // ── empty-result contract: a freshly created category has no files —
+    // text mode prints the friendly empty line and exits 0 (empty ≠ error) ──
+    const emptyCategoryListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "list",
+      "--category-id",
+      categoryId,
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(emptyCategoryListRun.exitCode, emptyCategoryListRun.stderr).toBe(0);
+    expect(emptyCategoryListRun.stdout).toMatch(/No files found\./);
+
+    const fixtureDir = mkdtempSync(join(tmpdir(), "param-e2e-"));
+    // Server contract (verified live): listFile fileName filters by the exact
+    // file name WITHOUT extension — keep the stem for the --name assertion below
+    const fileStem = `param-${Date.now()}`;
+    const filePath = join(fixtureDir, `${fileStem}.md`);
+    writeFileSync(filePath, "# e2e param file\n");
+    const uploadRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      filePath,
+      "--category-id",
+      categoryId,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+    const fileId = uploadRun.stdout.trim();
+    let indexId: string | undefined;
+
+    try {
+      // ── P2: file list --name —— exact match on the extension-less file name
+      // (e.g. a.md → pass a); fuzzy/partial keywords return an empty set.
+      // Poll to absorb list-visibility lag right after upload ──
+      const fileListByNamePoll = await pollUntil(
+        () =>
+          runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+            "knowledge",
+            "file",
+            "list",
+            "--category-id",
+            categoryId,
+            "--name",
+            fileStem,
+            "--workspace-id",
+            workspaceId,
+            "--quiet",
+          ]),
+        (run) => run.exitCode === 0 && run.stdout.trim().split("\n").includes(fileId),
+        { timeoutMs: 60_000, intervalMs: 5_000 },
+      );
+      expect(
+        fileListByNamePoll.satisfied,
+        `file list --name 未包含 ${fileId} (attempts=${fileListByNamePoll.attempts})`,
+      ).toBe(true);
+
+      // ── P2: file list --file-id ──
+      const fileListByFileIdRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "list",
+        "--category-id",
+        categoryId,
+        "--file-id",
+        fileId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(fileListByFileIdRun.exitCode, fileListByFileIdRun.stderr).toBe(0);
+      expect(fileListByFileIdRun.stdout.trim().split("\n")).toContain(fileId);
+
+      // ── P2: file list --max-result 1 ──
+      const fileListMaxResultRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "list",
+        "--category-id",
+        categoryId,
+        "--max-result",
+        "1",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(fileListMaxResultRun.exitCode, fileListMaxResultRun.stderr).toBe(0);
+      const maxResultLines = fileListMaxResultRun.stdout.trim().split("\n").filter(Boolean);
+      expect(maxResultLines.length).toBeLessThanOrEqual(1);
+
+      // ── P2: file list --next-token (if paginated) ──
+      const fileListJsonRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "list",
+        "--category-id",
+        categoryId,
+        "--max-result",
+        "1",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(fileListJsonRun.exitCode, fileListJsonRun.stderr).toBe(0);
+      const fileListData = parseStdoutJson<{
+        data?: { nextToken?: string };
+      }>(fileListJsonRun.stdout);
+      const fileNextToken = fileListData.data?.nextToken;
+      if (fileNextToken) {
+        const fileListNextTokenRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "list",
+          "--category-id",
+          categoryId,
+          "--next-token",
+          fileNextToken,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(fileListNextTokenRun.exitCode, fileListNextTokenRun.stderr).toBe(0);
+      }
+
+      // ── P3: category list --parent-id (using existing categoryId) ──
+      const listByParentRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--parent-id",
+        categoryId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listByParentRun.exitCode, listByParentRun.stderr).toBe(0);
+
+      // ── P3: category list --collection-id — an unknown collection id is rejected
+      // by the server (Invalid connectorId, verified live) and the error passes
+      // through verbatim with a non-zero exit ──
+      const listByCollectionRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "list",
+        "--collection-id",
+        "col_nonexistent_e2e",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listByCollectionRun.exitCode, "不存在的 collection id 应被服务端拒绝").not.toBe(0);
+      expect(listByCollectionRun.stderr).toMatch(/Invalid connectorId|InvalidParameter/i);
+
+      // ── create kb for chunk tests ──
+      const kbCreateRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "create",
+        "--name",
+        `e2e-pk-${Date.now() % 100000000}`.slice(0, 20),
+        "--doc-id",
+        fileId,
+        "--workspace-id",
+        workspaceId,
+        "--wait",
+        "--quiet",
+      ]);
+      expect(kbCreateRun.exitCode, kbCreateRun.stderr).toBe(0);
+      indexId = kbCreateRun.stdout.trim().split("\n")[0]!;
+      expect(indexId).toBeTruthy();
+
+      try {
+        // ── P4: chunk add --content-file ──
+        const chunkContentFile = join(fixtureDir, `chunk-${Date.now()}.txt`);
+        const chunkMarker = `e2e chunk content file marker ${Date.now()}`;
+        writeFileSync(chunkContentFile, chunkMarker);
+
+        const chunkAddFileRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "add",
+          "--index-id",
+          indexId,
+          "--doc-id",
+          fileId,
+          "--content-file",
+          chunkContentFile,
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(chunkAddFileRun.exitCode, chunkAddFileRun.stderr).toBe(0);
+
+        // chunk list read-back: verify content came from file
+        const chunkListAfterAddRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(chunkListAfterAddRun.exitCode, chunkListAfterAddRun.stderr).toBe(0);
+        const chunkListAfterAddData = parseStdoutJson<{
+          data?: {
+            nodes?: Array<{
+              metadata?: { _id?: string; content?: string };
+              text?: string;
+            }>;
+          };
+        }>(chunkListAfterAddRun.stdout);
+        const addedChunk = chunkListAfterAddData.data?.nodes?.find(
+          (node) => (node.metadata?.content ?? node.text) === chunkMarker,
+        );
+        expect(addedChunk?.metadata?.content ?? addedChunk?.text).toBe(chunkMarker);
+        const addedChunkId = addedChunk?.metadata?._id;
+        expect(addedChunkId).toBeTruthy();
+
+        // ── P6: chunk list --doc-id ──
+        const chunkListByDocRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--doc-id",
+          fileId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(chunkListByDocRun.exitCode, chunkListByDocRun.stderr).toBe(0);
+        const chunkListByDocData = parseStdoutJson<{
+          data?: {
+            nodes?: Array<{
+              metadata?: { doc_id?: string };
+            }>;
+          };
+        }>(chunkListByDocRun.stdout);
+        // All returned chunks should belong to the specified doc
+        for (const node of chunkListByDocData.data?.nodes ?? []) {
+          expect(node.metadata?.doc_id).toContain(fileId);
+        }
+
+        // ── empty-result contract: a page far past the end returns no chunks —
+        // text mode prints the friendly empty line and exits 0 (empty ≠ error) ──
+        const chunkListEmptyPageRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "list",
+          "--index-id",
+          indexId,
+          "--page-number",
+          "99",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(chunkListEmptyPageRun.exitCode, chunkListEmptyPageRun.stderr).toBe(0);
+        expect(chunkListEmptyPageRun.stdout).toMatch(/No chunks found\./);
+
+        // ── contract: updating a nonexistent chunk id — the server currently
+        // reports success (silent upsert-like semantics, verified live). The CLI
+        // passes the server result through without an existence pre-check; this
+        // assertion pins the known server behavior so a future server-side change
+        // (rejecting unknown ids) surfaces here immediately ──
+        const chunkUpdateMissingRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "chunk",
+          "update",
+          "--index-id",
+          indexId,
+          "--chunk-id",
+          "chunk_nonexistent_e2e_0000",
+          "--doc-id",
+          fileId,
+          "--content",
+          "content for a chunk id that should not exist",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(chunkUpdateMissingRun.exitCode, chunkUpdateMissingRun.stderr).toBe(0);
+        expect(chunkUpdateMissingRun.stdout).toMatch(/updated: chunk_nonexistent_e2e_0000/);
+
+        // ── P4: chunk update --content-file ──
+        if (addedChunkId) {
+          const updateContentFile = join(fixtureDir, `chunk-update-${Date.now()}.txt`);
+          const updateMarker = `e2e chunk update content file marker ${Date.now()}`;
+          writeFileSync(updateContentFile, updateMarker);
+
+          const chunkUpdateFileRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+            "knowledge",
+            "chunk",
+            "update",
+            "--index-id",
+            indexId,
+            "--chunk-id",
+            addedChunkId,
+            "--doc-id",
+            fileId,
+            "--content-file",
+            updateContentFile,
+            "--workspace-id",
+            workspaceId,
+          ]);
+          expect(chunkUpdateFileRun.exitCode, chunkUpdateFileRun.stderr).toBe(0);
+
+          // chunk list read-back: verify content changed
+          const chunkListAfterUpdateRun = await runCommandE2e(
+            KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES,
+            [
+              "knowledge",
+              "chunk",
+              "list",
+              "--index-id",
+              indexId,
+              "--workspace-id",
+              workspaceId,
+              "--output",
+              "json",
+            ],
+          );
+          expect(chunkListAfterUpdateRun.exitCode, chunkListAfterUpdateRun.stderr).toBe(0);
+          const chunkListAfterUpdateData = parseStdoutJson<{
+            data?: {
+              nodes?: Array<{
+                metadata?: { _id?: string; content?: string };
+                text?: string;
+              }>;
+            };
+          }>(chunkListAfterUpdateRun.stdout);
+          const updatedChunk = chunkListAfterUpdateData.data?.nodes?.find(
+            (node) => node.metadata?._id === addedChunkId,
+          );
+          expect(updatedChunk?.metadata?.content ?? updatedChunk?.text).toBe(updateMarker);
+        }
+      } finally {
+        // cleanup kb (retry for IndexStatusError)
+        if (indexId) {
+          let cleanupRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+            "knowledge",
+            "delete",
+            "--index-id",
+            indexId,
+            "--yes",
+            "--workspace-id",
+            workspaceId,
+          ]);
+          for (let retry = 0; retry < 5 && cleanupRun.exitCode !== 0; retry++) {
+            if (!cleanupRun.stderr.includes("IndexStatusError")) break;
+            await new Promise((resolve) => setTimeout(resolve, 10_000));
+            cleanupRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+              "knowledge",
+              "delete",
+              "--index-id",
+              indexId,
+              "--yes",
+              "--workspace-id",
+              workspaceId,
+            ]);
+          }
+        }
+      }
+    } finally {
+      // cleanup file + category
+      await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "file",
+        "delete",
+        "--file-id",
+        fileId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "delete",
+        "--category-id",
+        categoryId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+    }
+    // kb create --wait adds a full import phase — generous timeout
+  }, 600_000);
+});
+
+interface ChunkListNodes {
+  data?: { nodes?: Array<{ metadata?: Record<string, unknown> }> };
+}
+
+// Long-lived console-created fixture: the CLI can only create document-type bases,
+// so the field channel (table/image bases) rides on BAILIAN_E2E_TABLE_INDEX_ID.
+describe.skipIf(!isTableKbE2EReady())("e2e: chunk --field 表格库 live (常驻 fixture)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+  const tableIndexId = process.env.BAILIAN_E2E_TABLE_INDEX_ID!;
+
+  test("field 闭环: 取 doc_id → add --field → list 回读命中 → delete", async () => {
+    // Gotcha (verified live): dataId must be the document-level id from doc list;
+    // the per-row doc_id in chunk metadata (with a _<row> suffix) is rejected with
+    // Index.InvalidParameter
+    const docListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--index-id",
+      tableIndexId,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(docListRun.exitCode, docListRun.stderr).toBe(0);
+    const tableDocId = docListRun.stdout.trim().split("\n")[0];
+    expect(tableDocId, "表格 fixture 库应至少有 1 个文档").toBeTruthy();
+
+    // Server gotcha (verified live): table bases reject field chunks without --doc-id
+    // — HTTP 500 "dataId不能为空", passed through verbatim as a server error
+    const noDocIdRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      tableIndexId,
+      "--field",
+      "ZH=missing-doc-id-probe",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(noDocIdRun.exitCode).not.toBe(0);
+
+    // add a row via the field channel (ZH/KO are the fixture table's Excel headers)
+    const marker = `e2e-field-${Date.now()}`;
+    const addRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "add",
+      "--index-id",
+      tableIndexId,
+      "--doc-id",
+      tableDocId!,
+      "--field",
+      `ZH=${marker}`,
+      "--field",
+      "KO=e2e-probe",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(addRun.exitCode, addRun.stderr).toBe(0);
+
+    // read back by sweeping pages until the marker row shows up, grab its chunk id
+    let markerChunkId = "";
+    for (let pageNumber = 1; pageNumber <= 5 && !markerChunkId; pageNumber++) {
+      const pageRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "chunk",
+        "list",
+        "--index-id",
+        tableIndexId,
+        "--page-number",
+        String(pageNumber),
+        "--page-size",
+        "100",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(pageRun.exitCode, pageRun.stderr).toBe(0);
+      const pageNodes = parseStdoutJson<ChunkListNodes>(pageRun.stdout).data?.nodes ?? [];
+      const match = pageNodes.find((node) => node.metadata?.ZH === marker);
+      if (match) markerChunkId = (match.metadata?._id as string | undefined) ?? "";
+      if (pageNodes.length < 100) break;
+    }
+    expect(markerChunkId, `field 新增行未在 list 中回读到 (marker=${marker})`).toBeTruthy();
+
+    // clean up the exact row we added — the fixture base itself is never touched
+    const deleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "delete",
+      "--index-id",
+      tableIndexId,
+      "--chunk-id",
+      markerChunkId,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+  }, 120_000);
+});
+
+describe.skipIf(!isImageKbE2EReady())("e2e: 图片库 chunk 回读 live (常驻 fixture)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+  const imageIndexId = process.env.BAILIAN_E2E_IMAGE_INDEX_ID!;
+
+  test("chunk list 返回 image_url 数组与可见性标志", async () => {
+    const listRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "chunk",
+      "list",
+      "--index-id",
+      imageIndexId,
+      "--page-size",
+      "2",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(listRun.exitCode, listRun.stderr).toBe(0);
+    const nodes = parseStdoutJson<ChunkListNodes>(listRun.stdout).data?.nodes ?? [];
+    expect(nodes.length).toBeGreaterThan(0);
+    // Image-type chunks carry image_url arrays (shape verified against the live fixture)
+    const firstMeta = nodes[0]?.metadata ?? {};
+    expect(Array.isArray(firstMeta.image_url)).toBe(true);
+    expect((firstMeta.image_url as string[]).length).toBeGreaterThan(0);
+    expect(typeof firstMeta.is_displayed_chunk_content).toBe("boolean");
+  }, 60_000);
+});
+
+// Requires a bucket pre-authorized to the platform service role with a fixed test
+// object in place (see .env BAILIAN_E2E_OSS_BUCKET/REGION/KEY)
+describe.skipIf(!isOssImportE2EReady())("e2e: doc import-oss live (授权 bucket fixture)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+  const ossBucket = process.env.BAILIAN_E2E_OSS_BUCKET!;
+  const ossRegion = process.env.BAILIAN_E2E_OSS_REGION!;
+  const ossKey = process.env.BAILIAN_E2E_OSS_KEY!;
+
+  test("导入 → overwrite 重导(新 fileId, 旧 id 作废) → file delete 自清理", async () => {
+    // 1) first import returns a fileId (locks the addFileResultList response shape:
+    //    the docs' flat fileIds field is not returned — live-verified)
+    const importRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--bucket",
+      ossBucket,
+      "--region",
+      ossRegion,
+      "--oss-key",
+      ossKey,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(importRun.exitCode, importRun.stderr).toBe(0);
+    const firstFileId = importRun.stdout.trim();
+    expect(firstFileId).toMatch(/^file_/);
+
+    // 2) re-import with --overwrite: the server replaces the file and issues a NEW
+    //    fileId; the old one becomes invalid (live-verified semantics)
+    const overwriteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "doc",
+      "import-oss",
+      "--bucket",
+      ossBucket,
+      "--region",
+      ossRegion,
+      "--oss-key",
+      ossKey,
+      "--overwrite",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(overwriteRun.exitCode, overwriteRun.stderr).toBe(0);
+    const overwriteFileId = overwriteRun.stdout.trim();
+    expect(overwriteFileId).toMatch(/^file_/);
+    expect(overwriteFileId).not.toBe(firstFileId);
+
+    // the pre-overwrite id is gone — file get on it fails
+    const staleGetRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "get",
+      "--file-id",
+      firstFileId,
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(staleGetRun.exitCode).not.toBe(0);
+
+    // 3) clean up the surviving imported file
+    const deleteRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "file",
+      "delete",
+      "--file-id",
+      overwriteFileId,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+  }, 120_000);
+
+  test("collection create custom live: 幂等复用固定名自有存储集合", async () => {
+    // No collection delete API — fixed-name idempotent reuse, same pattern as the
+    // platform collection test. Requires the bucket tag
+    // bailian-connector-access=ReadAndWrite (tag-based access control).
+    const connectorName = "e2e-test-custom-conn"; // exactly 20 chars (server name limit)
+    const firstGetRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "get",
+      "--name",
+      connectorName,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    let connectorId = firstGetRun.exitCode === 0 ? firstGetRun.stdout.trim() : "";
+
+    if (!connectorId) {
+      const createRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "collection",
+        "create",
+        "--name",
+        connectorName,
+        "--description",
+        "e2e fixture custom connector (own OSS bucket, reused across runs)",
+        "--store-type",
+        "custom",
+        "--oss-region",
+        process.env.BAILIAN_E2E_OSS_REGION!,
+        "--oss-bucket",
+        process.env.BAILIAN_E2E_OSS_BUCKET!,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(createRun.exitCode, createRun.stderr).toBe(0);
+      connectorId = createRun.stdout.trim();
+    }
+    expect(connectorId).toBeTruthy();
+
+    // get by id: identity fields only — live-verified getConnector does NOT echo
+    // fileConnectorConfig (storeType/regionId/bucketName are absent from readback)
+    const getRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "collection",
+      "get",
+      "--collection-id",
+      connectorId,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(getRun.exitCode, getRun.stderr).toBe(0);
+    const customDetail = parseStdoutJson<{
+      data: { connectorId?: string; connectorName?: string; connectorType?: string };
+    }>(getRun.stdout);
+    expect(customDetail.data.connectorId).toBe(connectorId);
+    expect(customDetail.data.connectorName).toBe(connectorName);
+    expect(customDetail.data.connectorType).toBe("FILE");
+  }, 60_000);
+
+  test("import-oss --category-id --tag → file list + file get 读回验证", async () => {
+    // P5: verify --category-id and --tag params land on the server via read-back
+    const categoryName = `e2e-oss-cat-${Date.now() % 100000000}`;
+    const categoryAddRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+      "knowledge",
+      "category",
+      "add",
+      "--name",
+      categoryName,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(categoryAddRun.exitCode, categoryAddRun.stderr).toBe(0);
+    const categoryId = categoryAddRun.stdout.trim();
+    expect(categoryId).toMatch(/^cate_/);
+
+    try {
+      const importRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "doc",
+        "import-oss",
+        "--bucket",
+        ossBucket,
+        "--region",
+        ossRegion,
+        "--oss-key",
+        ossKey,
+        "--category-id",
+        categoryId,
+        "--tag",
+        "e2e-oss-tag",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(importRun.exitCode, importRun.stderr).toBe(0);
+      const fileId = importRun.stdout.trim();
+      expect(fileId).toMatch(/^file_/);
+
+      try {
+        // file list --category-id read-back: file is under the category
+        const fileListRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "list",
+          "--category-id",
+          categoryId,
+          "--workspace-id",
+          workspaceId,
+          "--quiet",
+        ]);
+        expect(fileListRun.exitCode, fileListRun.stderr).toBe(0);
+        expect(fileListRun.stdout.trim().split("\n")).toContain(fileId);
+
+        // file get read-back: tags contain "e2e-oss-tag"
+        const fileGetRun = await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "get",
+          "--file-id",
+          fileId,
+          "--workspace-id",
+          workspaceId,
+          "--output",
+          "json",
+        ]);
+        expect(fileGetRun.exitCode, fileGetRun.stderr).toBe(0);
+        const fileDetail = parseStdoutJson<{
+          data: { category?: string; tags?: unknown };
+        }>(fileGetRun.stdout);
+        expect(fileDetail.data.category).toBe(categoryId);
+        expect(JSON.stringify(fileDetail.data.tags ?? "")).toContain("e2e-oss-tag");
+      } finally {
+        await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+      }
+    } finally {
+      await runCommandE2e(KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES, [
+        "knowledge",
+        "category",
+        "delete",
+        "--category-id",
+        categoryId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+    }
+  }, 120_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-delete.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-delete.e2e.test.ts
new file mode 100644
index 00000000..dba73e3b
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-delete.e2e.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_DOC_DELETE_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge doc delete", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
+      "knowledge",
+      "doc",
+      "delete",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--doc-id/i);
+    expect(stderr).toMatch(/--yes/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
+      "knowledge",
+      "doc",
+      "delete",
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("缺 --doc-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
+      "knowledge",
+      "doc",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 doc_ids 数组 (snake_case)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
+      "knowledge",
+      "doc",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--doc-id",
+      "file_a",
+      "--doc-id",
+      "file_b",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string; request?: Record<string, unknown> }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/delete_file/);
+    expect(data.request?.index_id).toBe("idx_test");
+    expect(data.request?.doc_ids).toEqual(["file_a", "file_b"]);
+  });
+
+  test("非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_DELETE_ROUTES, [
+      "knowledge",
+      "doc",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--doc-id",
+      "file_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+});
+
+// Live coverage comes from the kb delete chain (deleting a knowledge base deletes
+// its documents); a standalone doc delete live case needs a "delete documents
+// without deleting the base" scenario, covered by the chunk/category/file live chain.
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-list.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-list.e2e.test.ts
new file mode 100644
index 00000000..3fb530d8
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-list.e2e.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_DOC_LIST_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge doc list", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--page-number/i);
+    expect(stderr).toMatch(/--page-size/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--page-size 101 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--index-id",
+      "idx_test",
+      "--page-size",
+      "101",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 query 参数名为 page_num (本接口坑位)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--dry-run",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--page-number",
+      "3",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/files/);
+    expect(data.endpoint).toMatch(/index_id=idx_test/);
+    expect(data.endpoint).toMatch(/page_num=3/);
+    expect(data.endpoint).not.toMatch(/page_number/);
+  });
+});
+
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc list (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("对真实库列出文档 (可为空)", async () => {
+    const listRun = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    const firstIndexId = listRun.stdout.trim().split("\n")[0];
+    if (!firstIndexId) return;
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--index-id",
+      firstIndexId,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ code: string }>(stdout);
+    expect(data.code).toBe("Success");
+
+    // P6: --page-number + --page-size
+    const pagedRun = await runCommandE2e(KNOWLEDGE_DOC_LIST_ROUTES, [
+      "knowledge",
+      "doc",
+      "list",
+      "--index-id",
+      firstIndexId,
+      "--page-number",
+      "1",
+      "--page-size",
+      "10",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(pagedRun.exitCode, pagedRun.stderr).toBe(0);
+    const pagedData = parseStdoutJson<{ code: string }>(pagedRun.stdout);
+    expect(pagedData.code).toBe("Success");
+  });
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts
new file mode 100644
index 00000000..31517ebb
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-status.e2e.test.ts
@@ -0,0 +1,254 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_DOC_STATUS_ROUTES } from "../topic-routes.ts";
+
+// Live coverage depends on a real job_id produced by doc upload; it is exercised
+// as part of the upload live chain.
+
+describe("e2e: knowledge doc status", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--job-id/i);
+    expect(stderr).toMatch(/--wait/i);
+    expect(stderr).toMatch(/--poll-interval/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--job-id",
+      "job_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("缺 --job-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 query 同时含两个 id (双必填坑位)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--dry-run",
+      "--index-id",
+      "idx_test",
+      "--job-id",
+      "job_test",
+      "--workspace-id",
+      "ws_test",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index_job\/status/);
+    expect(data.endpoint).toMatch(/index_id=idx_test/);
+    expect(data.endpoint).toMatch(/job_id=job_test/);
+  });
+
+  test("--dry-run 断言分页参数 query 透传", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--dry-run",
+      "--index-id",
+      "idx_test",
+      "--job-id",
+      "job_test",
+      "--page-number",
+      "2",
+      "--page-size",
+      "50",
+      "--workspace-id",
+      "ws_test",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string }>(stdout);
+    expect(data.endpoint).toMatch(/page_number=2/);
+    expect(data.endpoint).toMatch(/page_size=50/);
+  });
+});
+
+// Live: --wait + --poll-interval on a real job_id produced by upload --index-id --wait
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc status (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("不存在的 index/job: 服务端错误原样透传 (非零退出)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "status",
+      "--index-id",
+      "idx_nonexistent_e2e",
+      "--job-id",
+      "job_nonexistent_e2e",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(exitCode).not.toBe(0);
+    // Verified live: Index.IndexNotExist for an unknown index; a real index with
+    // an unknown job id reports Index.IndexJobNotExist — both pass through verbatim
+    expect(stderr).toMatch(/not exist/i);
+  }, 60_000);
+
+  test("status --wait --poll-interval → 返回 COMPLETED", async () => {
+    const fixtureDir = mkdtempSync(join(tmpdir(), "doc-status-e2e-"));
+    const filePathA = join(fixtureDir, `status-a-${Date.now()}.md`);
+    writeFileSync(filePathA, "# doc status e2e fixture A\n");
+
+    // 1) Upload file A to data center
+    const uploadRunA = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      filePathA,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(uploadRunA.exitCode, uploadRunA.stderr).toBe(0);
+    const fileIdA = uploadRunA.stdout.trim();
+    expect(fileIdA).toMatch(/^file_/);
+
+    let indexId = "";
+    let fileIdB = "";
+    try {
+      // 2) Create a throwaway base (gives us an index_id)
+      const createRun = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+        "knowledge",
+        "create",
+        "--name",
+        `e2e-st-${Date.now() % 100000000}`,
+        "--doc-id",
+        fileIdA,
+        "--workspace-id",
+        workspaceId,
+        "--wait",
+        "--quiet",
+      ]);
+      expect(createRun.exitCode, createRun.stderr).toBe(0);
+      indexId = createRun.stdout.trim().split("\n")[0]!;
+      expect(indexId).toBeTruthy();
+
+      // 3) Upload file B to the base (--index-id --wait --output json) → ingestion_id
+      const filePathB = join(fixtureDir, `status-b-${Date.now()}.md`);
+      writeFileSync(filePathB, "# doc status e2e fixture B\n");
+      const uploadRunB = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+        "knowledge",
+        "doc",
+        "upload",
+        "--file",
+        filePathB,
+        "--index-id",
+        indexId,
+        "--wait",
+        "--poll-interval",
+        "3",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(uploadRunB.exitCode, uploadRunB.stderr).toBe(0);
+      const importData = parseStdoutJson<{
+        files: Array<{ fileId: string }>;
+        ingestion_id?: string;
+        final_status?: string;
+      }>(uploadRunB.stdout);
+      const jobId = importData.ingestion_id;
+      expect(jobId).toBeTruthy();
+      fileIdB = importData.files?.[0]?.fileId ?? "";
+
+      // 4) status --wait --poll-interval: verify COMPLETED
+      //    (upload --wait already ensured completion, so this should return immediately)
+      const statusRun = await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+        "knowledge",
+        "doc",
+        "status",
+        "--index-id",
+        indexId,
+        "--job-id",
+        jobId!,
+        "--wait",
+        "--poll-interval",
+        "3",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(statusRun.exitCode, statusRun.stderr).toBe(0);
+      // JSON mode passes the server response through — the job state field is
+      // ingestion_status (final_status only exists in doc upload's own output)
+      const statusData = parseStdoutJson<{
+        data?: { ingestion_status?: string };
+      }>(statusRun.stdout);
+      expect(statusData.data?.ingestion_status).toBe("COMPLETED");
+    } finally {
+      // Cleanup base + data-center files
+      if (fileIdB) {
+        await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          fileIdB,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+      }
+      if (indexId) {
+        await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+          "knowledge",
+          "delete",
+          "--index-id",
+          indexId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+      }
+      await runCommandE2e(KNOWLEDGE_DOC_STATUS_ROUTES, [
+        "knowledge",
+        "file",
+        "delete",
+        "--file-id",
+        fileIdA,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+    }
+    // kb create --wait adds a full import phase — generous timeout
+  }, 600_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-tag.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-tag.e2e.test.ts
new file mode 100644
index 00000000..b3facd35
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-tag.e2e.test.ts
@@ -0,0 +1,310 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_DOC_TAG_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge doc tag", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--doc-id/i);
+    expect(stderr).toMatch(/--tag/i);
+    expect(stderr).toMatch(/--mode/i);
+  });
+
+  test("缺 --doc-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--tag",
+      "demo",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("缺 --tag 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("21 个 --doc-id 报 USAGE (2)", async () => {
+    const docIdArgs = Array.from({ length: 21 }, (_, docIndex) => [
+      "--doc-id",
+      `file_${docIndex}`,
+    ]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      ...docIdArgs,
+      "--tag",
+      "demo",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("33 字符标签报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      "--tag",
+      "x".repeat(33),
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("101 个标签报 USAGE (2)", async () => {
+    const tagArgs = Array.from({ length: 101 }, (_, tagIndex) => ["--tag", `t${tagIndex}`]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      ...tagArgs,
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("标签总长超 700 字符报 USAGE (2)", async () => {
+    // 25 tags × 32 chars = 800 > 700, while each tag and the count stay within limits
+    const tagArgs = Array.from({ length: 25 }, () => ["--tag", "x".repeat(32)]).flat();
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      ...tagArgs,
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--mode 非法值报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      "--tag",
+      "demo",
+      "--mode",
+      "replace",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 updateMode 大写映射与 fileInfos 结构", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_a",
+      "--doc-id",
+      "file_b",
+      "--tag",
+      "alpha",
+      "--tag",
+      "beta",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{
+      endpoint?: string;
+      request?: { fileInfos?: Array<{ fileId: string; tags: string[] }>; updateMode?: string };
+    }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/connector\/dash\/batchUpdateFileTag/);
+    expect(data.request?.updateMode).toBe("APPEND");
+    expect(data.request?.fileInfos).toEqual([
+      { fileId: "file_a", tags: ["alpha", "beta"] },
+      { fileId: "file_b", tags: ["alpha", "beta"] },
+    ]);
+  });
+
+  test("--dry-run 断言 --mode overwrite 大写映射 OVERWRITE", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_test",
+      "--tag",
+      "final",
+      "--mode",
+      "overwrite",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ request?: { updateMode?: string } }>(stdout);
+    expect(data.request?.updateMode).toBe("OVERWRITE");
+  });
+});
+
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc tag (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("不存在的 doc-id: 服务端静默成功契约 (已知行为锁定)", async () => {
+    // The tag API currently reports success for an unknown doc id (verified
+    // live) — the CLI passes the server result through without an existence
+    // pre-check. This pins the known server behavior so a future server-side
+    // change (rejecting unknown ids) surfaces here immediately
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      "file_nonexistent_e2e_0000",
+      "--tag",
+      "e2e-nonexistent-doc",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stdout).toMatch(/tagged: 1 file\(s\)/);
+  }, 60_000);
+
+  test("对新上传文件打标断言 Success", async () => {
+    const fixtureDir = mkdtempSync(join(tmpdir(), "doc-tag-e2e-"));
+    const filePath = join(fixtureDir, `tag-${Date.now()}.md`);
+    writeFileSync(filePath, "# doc tag e2e fixture\n");
+    const uploadRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      filePath,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+    const fileId = uploadRun.stdout.trim();
+
+    const tagRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      fileId,
+      "--tag",
+      "e2e-tag",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(tagRun.exitCode, tagRun.stderr).toBe(0);
+    const data = parseStdoutJson<{ code: string }>(tagRun.stdout);
+    expect(data.code).toBe("Success");
+
+    // Verify the tag actually landed on the server via an independent read-back
+    const tagGetRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "file",
+      "get",
+      "--file-id",
+      fileId,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(tagGetRun.exitCode, tagGetRun.stderr).toBe(0);
+    const tagGetDetail = parseStdoutJson<{ data: { tags?: string[] } }>(tagGetRun.stdout);
+    expect(tagGetDetail.data?.tags ?? []).toContain("e2e-tag");
+
+    // overwrite mode replaces the tag set live (append above covered the default)
+    const overwriteRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "doc",
+      "tag",
+      "--doc-id",
+      fileId,
+      "--tag",
+      "e2e-tag-final",
+      "--mode",
+      "overwrite",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(overwriteRun.exitCode, overwriteRun.stderr).toBe(0);
+    const overwriteData = parseStdoutJson<{ code: string }>(overwriteRun.stdout);
+    expect(overwriteData.code).toBe("Success");
+
+    // Verify overwrite replaced the tag set — old tag gone, new tag present
+    const overwriteGetRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "file",
+      "get",
+      "--file-id",
+      fileId,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(overwriteGetRun.exitCode, overwriteGetRun.stderr).toBe(0);
+    const overwriteGetDetail = parseStdoutJson<{ data: { tags?: string[] } }>(
+      overwriteGetRun.stdout,
+    );
+    const overwriteTags = overwriteGetDetail.data?.tags ?? [];
+    expect(overwriteTags).toContain("e2e-tag-final");
+    expect(overwriteTags).not.toContain("e2e-tag");
+
+    // Clean up the uploaded data-center file
+    const fileDeleteRun = await runCommandE2e(KNOWLEDGE_DOC_TAG_ROUTES, [
+      "knowledge",
+      "file",
+      "delete",
+      "--file-id",
+      fileId,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
+  }, 120_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-doc-upload.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-doc-upload.e2e.test.ts
new file mode 100644
index 00000000..8890575e
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-doc-upload.e2e.test.ts
@@ -0,0 +1,384 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_DOC_UPLOAD_ROUTES } from "../topic-routes.ts";
+
+const fixtureDir = mkdtempSync(join(tmpdir(), "doc-upload-e2e-"));
+const smallMd = join(fixtureDir, "small.md");
+writeFileSync(smallMd, "# e2e fixture\n");
+
+interface DryRunStep {
+  step: string;
+  endpoint: string;
+  request: unknown;
+}
+
+describe("e2e: knowledge doc upload", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--file/i);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--category-id/i);
+    expect(stderr).toMatch(/--tag/i);
+    expect(stderr).toMatch(/--wait/i);
+  });
+
+  test("缺 --file 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--wait 无 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      smallMd,
+      "--wait",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("文件不存在非零退出且 hint 含 errno", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      join(fixtureDir, "missing.md"),
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatch(/ENOENT|Cannot read file/i);
+  });
+
+  test(".zip 扩展名报 USAGE 并列出支持格式", async () => {
+    const zipPath = join(fixtureDir, "bad.zip");
+    writeFileSync(zipPath, "PK");
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      zipPath,
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/\.pdf/);
+  });
+
+  test("--dry-run 不带 --index-id 输出 3 步编排计划", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      smallMd,
+      "--category-id",
+      "cate_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ steps: DryRunStep[]; skipped: string[] }>(stdout);
+    expect(data.steps).toHaveLength(3);
+    const leaseRequest = data.steps[0]!.request as { sizeBytes?: unknown; category?: string };
+    expect(typeof leaseRequest.sizeBytes).toBe("string"); // gotcha: sizeBytes must be a string
+    expect(leaseRequest.category).toBe("cate_test");
+    // Single file path → no skipped entries
+    expect(data.skipped).toEqual([]);
+  });
+
+  test("--dry-run 带 --index-id 输出 4 步且 job 请求含扁平 docIds", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      smallMd,
+      "--category-id",
+      "cate_test",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ steps: DryRunStep[]; skipped: string[] }>(stdout);
+    expect(data.steps).toHaveLength(4);
+    const jobRequest = data.steps[3]!.request as {
+      indexId?: string;
+      sourceType?: string;
+      docIds?: string[];
+    };
+    // Live-verified: the field name is docIds (not documentIds as in the
+    // public docs); omitting sourceType would import the entire data center.
+    expect(jobRequest.sourceType).toBe("DATA_CENTER_FILE");
+    expect(jobRequest.docIds).toEqual(["<fileId>"]);
+    expect(jobRequest.indexId).toBe("idx_test");
+    expect(jobRequest).not.toHaveProperty("dataSource");
+  });
+
+  test("--file <dir> dry-run 展开目录且 skipped 包含不支持的文件", async () => {
+    const dirFixture = mkdtempSync(join(tmpdir(), "doc-upload-dir-e2e-"));
+    writeFileSync(join(dirFixture, "readme.md"), "# dir fixture\n");
+    writeFileSync(join(dirFixture, "data.csv"), "a,b,c");
+    writeFileSync(join(dirFixture, "config.json"), "{}"); // unsupported
+    const subDir = join(dirFixture, "sub");
+    mkdirSync(subDir);
+    writeFileSync(join(subDir, "notes.txt"), "hello");
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      dirFixture,
+      "--category-id",
+      "cate_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ steps: DryRunStep[]; skipped: string[] }>(stdout);
+    // 3 supported files × 3 steps each = 9 steps
+    expect(data.steps).toHaveLength(9);
+    // config.json is the only unsupported file
+    expect(data.skipped).toHaveLength(1);
+    expect(data.skipped[0]).toMatch(/config\.json$/);
+  });
+
+  test("--file <dir> 仅含不支持的文件报 USAGE", async () => {
+    const unsupportedDir = mkdtempSync(join(tmpdir(), "doc-upload-unsupported-"));
+    writeFileSync(join(unsupportedDir, "data.json"), "{}");
+    writeFileSync(join(unsupportedDir, "script.py"), "print(1)");
+
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      unsupportedDir,
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/No supported files found/i);
+  });
+
+  test("--file <dir> 自动跳过 node_modules/.git，其中文件不进 steps 也不进 skipped", async () => {
+    const toolingDir = mkdtempSync(join(tmpdir(), "doc-upload-tooling-"));
+    writeFileSync(join(toolingDir, "guide.md"), "# business doc\n");
+    const nodeModulesDir = join(toolingDir, "node_modules");
+    mkdirSync(nodeModulesDir);
+    writeFileSync(join(nodeModulesDir, "vendored.md"), "# should never upload\n");
+    const gitDir = join(toolingDir, ".git");
+    mkdirSync(gitDir);
+    writeFileSync(join(gitDir, "COMMIT_EDITMSG.txt"), "message");
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      toolingDir,
+      "--category-id",
+      "cate_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ steps: DryRunStep[]; skipped: string[] }>(stdout);
+    // Only guide.md is planned: 1 file × 3 steps
+    expect(data.steps).toHaveLength(3);
+    // Tooling directories are skipped silently — not even listed as skipped
+    expect(data.skipped).toEqual([]);
+    expect(JSON.stringify(data.steps)).not.toMatch(/vendored\.md|COMMIT_EDITMSG/);
+  });
+});
+
+// Live write artifacts (data-center files) are cleaned up in place via the file delete command.
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc upload (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("0KB 空文件被服务端拒绝：非零退出且透传服务端原因", async () => {
+    const emptyPath = join(fixtureDir, `empty-${Date.now()}.md`);
+    writeFileSync(emptyPath, "");
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      emptyPath,
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(exitCode).not.toBe(0);
+    // Server message passed through verbatim (lease rejects an empty SizeInBytes)
+    expect(stderr).toMatch(/empty|SizeInBytes|InvalidParameter/i);
+  }, 60_000);
+
+  test("目录上传 --verbose 列出跳过文件明细与汇总计数", async () => {
+    const verboseDir = mkdtempSync(join(tmpdir(), "doc-upload-verbose-"));
+    writeFileSync(join(verboseDir, `verbose-${Date.now()}.md`), "# e2e verbose fixture\n");
+    writeFileSync(join(verboseDir, "unsupported.xyz"), "skip me");
+
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      verboseDir,
+      "--workspace-id",
+      workspaceId,
+      "--verbose",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    // Summary line always shows both counts; --verbose adds the skipped detail list
+    expect(stdout).toMatch(/Uploaded 1 file, skipped 1 unsupported\./);
+    expect(stdout).toMatch(/Skipped files:/);
+    expect(stdout).toMatch(/unsupported\.xyz/);
+
+    // Extract the fileId from the text output (`<name>  <fileId>  registered`) and clean up
+    const fileId = stdout.match(/\s(file_\S+)\s+registered/)?.[1];
+    expect(fileId, `无法从输出提取 fileId: ${stdout}`).toBeTruthy();
+    const fileDeleteRun = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "file",
+      "delete",
+      "--file-id",
+      fileId!,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
+  }, 120_000);
+
+  test("上传 2 个 md 返回各自 file_ 前缀 fileId (多文件 happy path)", async () => {
+    const livePathA = join(fixtureDir, `live-a-${Date.now()}.md`);
+    const livePathB = join(fixtureDir, `live-b-${Date.now()}.md`);
+    writeFileSync(livePathA, "# e2e live upload fixture A\n");
+    writeFileSync(livePathB, "# e2e live upload fixture B\n");
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      livePathA,
+      "--file",
+      livePathB,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const fileIds = stdout.trim().split("\n").filter(Boolean);
+    expect(fileIds).toHaveLength(2);
+    for (const fileId of fileIds) {
+      expect(fileId).toMatch(/^file_/);
+    }
+
+    // Clean up both uploaded data-center files
+    for (const fileId of fileIds) {
+      const fileDeleteRun = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+        "knowledge",
+        "file",
+        "delete",
+        "--file-id",
+        fileId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
+    }
+  }, 120_000);
+
+  test("upload --index-id --wait --poll-interval 3 (不报错验证)", async () => {
+    // P6: --poll-interval — local behavior param, verify no error
+    // Grab a real index id from the workspace
+    const listRun = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(listRun.exitCode, listRun.stderr).toBe(0);
+    const indexId = listRun.stdout.trim().split("\n")[0];
+    if (!indexId) return;
+
+    const pollFilePath = join(fixtureDir, `poll-${Date.now()}.md`);
+    writeFileSync(pollFilePath, "# e2e poll interval fixture\n");
+    const uploadRun = await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+      "knowledge",
+      "doc",
+      "upload",
+      "--file",
+      pollFilePath,
+      "--index-id",
+      indexId,
+      "--wait",
+      "--poll-interval",
+      "3",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+
+    // Cleanup the uploaded file
+    const importData = parseStdoutJson<{
+      files: Array<{ fileId: string }>;
+    }>(uploadRun.stdout);
+    const pollFileId = importData.files?.[0]?.fileId;
+    if (pollFileId) {
+      await runCommandE2e(KNOWLEDGE_DOC_UPLOAD_ROUTES, [
+        "knowledge",
+        "file",
+        "delete",
+        "--file-id",
+        pollFileId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+    }
+  }, 120_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts
new file mode 100644
index 00000000..651ee64f
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-create.e2e.test.ts
@@ -0,0 +1,156 @@
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_KB_CREATE_ROUTES } from "../topic-routes.ts";
+
+interface DryRunBody {
+  endpoint?: string;
+  request?: {
+    sourceType?: string;
+    sinkType?: string;
+    docIds?: string[];
+    categoryIds?: string[];
+    embeddingModelName?: string;
+    chunkSize?: number;
+  };
+}
+
+describe("e2e: knowledge kb create", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--name/i);
+    expect(stderr).toMatch(/--doc-id/i);
+    expect(stderr).toMatch(/--category-id/i);
+    expect(stderr).toMatch(/--embedding-model/i);
+    expect(stderr).toMatch(/--chunk-size/i);
+  });
+
+  test("缺 --name 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("无数据源 flag 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "demo",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("两数据源同传报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "demo",
+      "--doc-id",
+      "file_test",
+      "--category-id",
+      "cate_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--name 21 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "x".repeat(21),
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run + --doc-id 断言 DATA_CENTER_FILE / docIds / BUILT_IN", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "demo",
+      "--doc-id",
+      "file_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/create_v2/);
+    expect(data.request?.sourceType).toBe("DATA_CENTER_FILE");
+    expect(data.request?.docIds).toEqual(["file_test"]);
+    expect(data.request?.sinkType).toBe("BUILT_IN");
+    // Defaults are part of the contract — the server applies no fallback of its own
+    expect(data.request?.embeddingModelName).toBe("text-embedding-v4");
+    expect(data.request?.chunkSize).toBe(600);
+  });
+
+  test("--dry-run 断言 --embedding-model/--chunk-size 在 body 中的映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "demo",
+      "--doc-id",
+      "file_test",
+      "--embedding-model",
+      "text-embedding-v3",
+      "--chunk-size",
+      "300",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.embeddingModelName).toBe("text-embedding-v3");
+    expect(data.request?.chunkSize).toBe(300);
+  });
+
+  test("--dry-run + --category-id 断言 DATA_CENTER_CATEGORY / categoryIds", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
+      "knowledge",
+      "create",
+      "--name",
+      "demo",
+      "--category-id",
+      "cate_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.sourceType).toBe("DATA_CENTER_CATEGORY");
+    expect(data.request?.categoryIds).toEqual(["cate_test"]);
+  });
+});
+
+// The live self-cleaning chain lives in knowledge-kb-delete.e2e.test.ts (upload → create → delete).
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts
new file mode 100644
index 00000000..d19bce90
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-delete.e2e.test.ts
@@ -0,0 +1,282 @@
+// The live group chains the full lifecycle: upload → create → update → upload --index-id
+// (import orchestration) → delete → list to verify removal.
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { deleteKbWithRetry } from "./journeys/journey-helpers.ts";
+import { KNOWLEDGE_KB_DELETE_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge kb delete", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+      "knowledge",
+      "delete",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--yes/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+      "knowledge",
+      "delete",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 body index_id (snake_case)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+      "knowledge",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string; request?: Record<string, unknown> }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/delete/);
+    expect(data.request?.index_id).toBe("idx_test");
+  });
+
+  test("非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+      "knowledge",
+      "delete",
+      "--index-id",
+      "idx_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+});
+
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge kb 写链路 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("upload → create → update → upload --index-id → delete → list 验证消失", async () => {
+    // Mid-chain failures must not leak the base / data-center files — track created
+    // resources and best-effort clean them in finally (only when the chain aborted)
+    const fixtureFileIds: string[] = [];
+    let indexId = "";
+    let chainCompleted = false;
+    try {
+      // 1) Upload a file
+      const fixtureDir = mkdtempSync(join(tmpdir(), "kb-chain-e2e-"));
+      const filePath = join(fixtureDir, `chain-${Date.now()}.md`);
+      writeFileSync(filePath, "# kb chain e2e fixture\n");
+      const uploadRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "doc",
+        "upload",
+        "--file",
+        filePath,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(uploadRun.exitCode, uploadRun.stderr).toBe(0);
+      const fileId = uploadRun.stdout.trim();
+      expect(fileId).toMatch(/^file_/);
+      fixtureFileIds.push(fileId);
+
+      // 2) Create the knowledge base (--wait for the import; server gotcha: a freshly
+      //    created base cannot be deleted immediately — Index.IndexStatusError)
+      const kbName = `e2e-del-${Date.now() % 100000000}`;
+      const createRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "create",
+        "--name",
+        kbName,
+        "--doc-id",
+        fileId,
+        "--workspace-id",
+        workspaceId,
+        "--wait",
+        "--poll-interval",
+        "3",
+        "--quiet",
+      ]);
+      expect(createRun.exitCode, createRun.stderr).toBe(0);
+      indexId = createRun.stdout.trim().split("\n")[0]!;
+      expect(indexId).toBeTruthy();
+
+      // 2.5) Live update coverage: name / description / rerank threshold in one call
+      const updatedName = `e2e-upd-${Date.now() % 100000000}`;
+      const updateRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "update",
+        "--index-id",
+        indexId,
+        "--name",
+        updatedName,
+        "--description",
+        "e2e chain updated description",
+        "--rerank-min-score",
+        "0.3",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(updateRun.exitCode, updateRun.stderr).toBe(0);
+      expect(updateRun.stdout).toMatch(/updated/);
+
+      // 2.6) Verify the update actually landed on the server — not just that the
+      //      command returned Success, but that a fresh read-back shows the new values
+      const infoRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "info",
+        "--index-id",
+        indexId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(infoRun.exitCode, infoRun.stderr).toBe(0);
+      const infoData = parseStdoutJson<{
+        name?: string;
+        description?: string;
+        rerankMinScore?: number;
+      }>(infoRun.stdout);
+      expect(infoData.name).toBe(updatedName);
+      expect(infoData.description).toBe("e2e chain updated description");
+      expect(infoData.rerankMinScore).toBe(0.3);
+
+      // 2.7) Live coverage of the upload → import orchestration (doc upload --index-id --wait):
+      //      the journeys always upload bare files and import via kb create, so this is the
+      //      only place the createImportJob step runs live. Using --output json (not --quiet)
+      //      so we can assert final_status and ingestion_id — a regression in the job/create
+      //      request body (e.g. wrong field name) is caught by the server returning HTTP 400.
+      const importFilePath = join(fixtureDir, `chain-import-${Date.now()}.md`);
+      writeFileSync(importFilePath, "# kb chain e2e import fixture\n");
+      const importUploadRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "doc",
+        "upload",
+        "--file",
+        importFilePath,
+        "--index-id",
+        indexId,
+        "--wait",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(importUploadRun.exitCode, importUploadRun.stderr).toBe(0);
+      const importData = parseStdoutJson<{
+        files: Array<{ fileId: string }>;
+        ingestion_id?: string;
+        final_status?: string;
+      }>(importUploadRun.stdout);
+      // These assertions verify the full pipeline completed: ingestion_id proves the
+      // job was created, and final_status COMPLETED proves parsing finished successfully.
+      expect(importData.ingestion_id).toBeTruthy();
+      expect(importData.final_status).toBe("COMPLETED");
+      const importedFileId = importData.files?.[0]?.fileId;
+      expect(importedFileId).toMatch(/^file_/);
+      fixtureFileIds.push(importedFileId);
+
+      // 2.8) Verify the imported file is actually visible in the KB — final_status
+      //      COMPLETED only proves the job finished; an independent doc list query
+      //      confirms the file was registered as a document in the index
+      const docListRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "doc",
+        "list",
+        "--index-id",
+        indexId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(docListRun.exitCode, docListRun.stderr).toBe(0);
+      const docListData = parseStdoutJson<{
+        data?: { rows?: Array<{ doc_name?: string; status?: string }> };
+      }>(docListRun.stdout);
+      // doc_name drops the file extension (e.g. "foo.md" → "foo"); match by stem
+      const importedFileStem = basename(importFilePath).replace(/\.[^.]+$/, "");
+      const importedDoc = docListData.data?.rows?.find((row) =>
+        row.doc_name?.includes(importedFileStem),
+      );
+      expect(importedDoc, `expected doc list to contain file "${importedFileStem}"`).toBeTruthy();
+
+      // 3) Delete the base (--yes non-interactive; deleteKbWithRetry retries on
+      //    IndexStatusError: readiness can lag briefly even after the import completes)
+      const deleteRun = await deleteKbWithRetry(
+        (args) => runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, args),
+        indexId,
+        workspaceId,
+      );
+      expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+      expect(deleteRun.stdout).toMatch(/deleted/);
+
+      // 3.5) Clean up the data-center files (kb delete removes them from the base but
+      //      the file artifacts persist in the data center)
+      for (const cleanupFileId of fixtureFileIds) {
+        const fileDeleteRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+          "knowledge",
+          "file",
+          "delete",
+          "--file-id",
+          cleanupFileId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+        expect(fileDeleteRun.exitCode, fileDeleteRun.stderr).toBe(0);
+      }
+
+      // 4) list verifies the base is gone
+      const listRun = await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+        "knowledge",
+        "list",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listRun.exitCode, listRun.stderr).toBe(0);
+      const remainingIds = listRun.stdout.trim().split("\n");
+      expect(remainingIds).not.toContain(indexId);
+      chainCompleted = true;
+    } finally {
+      if (!chainCompleted) {
+        // Best-effort cleanup on abort — do not assert, the original failure matters more
+        if (indexId) {
+          await deleteKbWithRetry(
+            (args) => runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, args),
+            indexId,
+            workspaceId,
+          );
+        }
+        for (const cleanupFileId of fixtureFileIds) {
+          await runCommandE2e(KNOWLEDGE_KB_DELETE_ROUTES, [
+            "knowledge",
+            "file",
+            "delete",
+            "--file-id",
+            cleanupFileId,
+            "--yes",
+            "--workspace-id",
+            workspaceId,
+          ]);
+        }
+      }
+    }
+    // Two --wait import phases in the chain — timeout sized for slow server-side parsing
+  }, 600_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-info.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-info.e2e.test.ts
new file mode 100644
index 00000000..be0206bc
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-info.e2e.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_KB_INFO_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge kb info", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "info",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--workspace-id/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "info",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--index-id|Usage:/i);
+  });
+
+  test("--dry-run 输出 list endpoint (含 pipeline_id 过滤)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "info",
+      "--dry-run",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/list/);
+    expect(data.endpoint).toMatch(/pipeline_id=idx_test/);
+  });
+});
+
+interface KbListQuietResult {
+  stdout: string;
+}
+
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge kb info (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("先 list 取 id 再 info 断言分组字段", async () => {
+    const listRun: KbListQuietResult = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    const firstId = listRun.stdout.trim().split("\n")[0];
+    if (!firstId) return; // skip assertions when the workspace has no knowledge bases
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "info",
+      "--index-id",
+      firstId,
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stdout).toMatch(/Basic:/);
+    expect(stdout).toMatch(/Indexing:/);
+    expect(stdout).toMatch(/immutable/);
+    expect(stdout).toMatch(/Retrieval:/);
+  });
+
+  test("不存在的 id 非零退出并给 hint", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_INFO_ROUTES, [
+      "knowledge",
+      "info",
+      "--index-id",
+      "idx-not-exist-e2e",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatch(/not found/i);
+  });
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-list.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-list.e2e.test.ts
new file mode 100644
index 00000000..af1063bd
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-list.e2e.test.ts
@@ -0,0 +1,174 @@
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_KB_LIST_ROUTES } from "../topic-routes.ts";
+
+interface DryRunBody {
+  endpoint?: string;
+  request?: unknown;
+}
+
+describe("e2e: knowledge kb list", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--name/i);
+    expect(stderr).toMatch(/--page-number/i);
+    expect(stderr).toMatch(/--page-size/i);
+    expect(stderr).toMatch(/--workspace-id/i);
+  });
+
+  test("缺 workspace 时报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_LIST_ROUTES,
+      ["knowledge", "list", "--api-key", "sk-fake", "--output", "json"],
+      { BAILIAN_WORKSPACE_ID: "", BAILIAN_CONFIG_DIR: "/tmp" },
+    );
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/workspace.*required/i);
+  });
+
+  test("--dry-run 输出 endpoint (query string 含分页/过滤参数)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--dry-run",
+      "--workspace-id",
+      "ws_test",
+      "--name",
+      "demo",
+      "--page-number",
+      "2",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/ws_test\.cn-beijing\.maas\.aliyuncs\.com/);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/list/);
+    expect(data.endpoint).toMatch(/page_number=2/);
+    expect(data.endpoint).toMatch(/pipeline_name=demo/);
+    expect(data.request).toBeNull();
+  });
+
+  test("--name 21 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--dry-run",
+      "--workspace-id",
+      "ws_test",
+      "--name",
+      "x".repeat(21),
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--page-size 101 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--dry-run",
+      "--workspace-id",
+      "ws_test",
+      "--page-size",
+      "101",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+});
+
+interface KbListResponse {
+  code: string;
+  data: { rows: Array<{ id: string; name: string }> };
+}
+
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge kb list (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("list 返回 rows 数组", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<KbListResponse>(stdout);
+    expect(data.code).toBe("Success");
+    expect(Array.isArray(data.data.rows)).toBe(true);
+  });
+
+  test("--quiet 输出行数与 rows 数一致", async () => {
+    const jsonRun = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    const rows = parseStdoutJson<KbListResponse>(jsonRun.stdout).data.rows;
+    const quietRun = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    const lines = quietRun.stdout.trim().split("\n").filter(Boolean);
+    expect(lines.length).toBe(rows.length);
+  });
+
+  test("--name 过滤 + --page-number/--page-size 分页", async () => {
+    // P6: --name
+    const jsonRun = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(jsonRun.exitCode, jsonRun.stderr).toBe(0);
+    const allRows = parseStdoutJson<KbListResponse>(jsonRun.stdout).data.rows;
+    if (allRows.length === 0) return;
+
+    const firstName = allRows[0]!.name;
+    const nameRun = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--name",
+      firstName,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(nameRun.exitCode, nameRun.stderr).toBe(0);
+    const nameData = parseStdoutJson<KbListResponse>(nameRun.stdout);
+    expect(nameData.data.rows.some((row) => row.name === firstName)).toBe(true);
+
+    // P6: --page-number + --page-size
+    const pagedRun = await runCommandE2e(KNOWLEDGE_KB_LIST_ROUTES, [
+      "knowledge",
+      "list",
+      "--page-number",
+      "1",
+      "--page-size",
+      "1",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(pagedRun.exitCode, pagedRun.stderr).toBe(0);
+    const pagedData = parseStdoutJson<KbListResponse>(pagedRun.stdout);
+    expect(pagedData.data.rows.length).toBeLessThanOrEqual(1);
+  });
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-stats.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-stats.e2e.test.ts
new file mode 100644
index 00000000..b6ce179c
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-stats.e2e.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_KB_STATS_ROUTES } from "../topic-routes.ts";
+
+interface DryRunBody {
+  endpoint?: string;
+  request?: {
+    indexId?: string;
+    startTimestamp?: string;
+    endTimestamp?: string;
+  };
+}
+
+describe("e2e: knowledge stats dry-run", () => {
+  test("--dry-run 正常日期范围输出正确时间戳", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      [
+        "knowledge",
+        "stats",
+        "--dry-run",
+        "--index-id",
+        "idx_test",
+        "--start",
+        "2026-07-30",
+        "--end",
+        "2026-08-10",
+        "--workspace-id",
+        "ws_test",
+        "--output",
+        "json",
+      ],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/monitor/);
+    expect(data.request?.indexId).toBe("idx_test");
+    expect(data.request?.startTimestamp).toBe("1785369600"); // 2026-07-30 00:00:00 UTC
+    expect(data.request?.endTimestamp).toBe("1786320000"); // 2026-08-10 00:00:00 UTC (11 days after start)
+  });
+
+  test("--end 未来时间被截断为当前时间", async () => {
+    const beforeRun = Math.floor(Date.now() / 1000);
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      [
+        "knowledge",
+        "stats",
+        "--dry-run",
+        "--index-id",
+        "idx_test",
+        "--start",
+        "2026-07-30",
+        "--end",
+        "2026-12-31",
+        "--workspace-id",
+        "ws_test",
+        "--output",
+        "json",
+      ],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    const afterRun = Math.floor(Date.now() / 1000);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.startTimestamp).toBe("1785369600"); // 2026-07-30 unchanged
+    // endTimestamp should be clamped to now, within the run window
+    const endTs = Number(data.request?.endTimestamp);
+    expect(endTs).toBeGreaterThanOrEqual(beforeRun);
+    expect(endTs).toBeLessThanOrEqual(afterRun);
+  });
+
+  test("--start 未来时间报用法错误 (exit 2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      [
+        "knowledge",
+        "stats",
+        "--dry-run",
+        "--index-id",
+        "idx_test",
+        "--start",
+        "2026-12-31",
+        "--workspace-id",
+        "ws_test",
+        "--output",
+        "json",
+      ],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/future/i);
+  });
+
+  test("--start 非法时间格式报用法错误 (exit 2) 且 hint 给出合法格式", async () => {
+    const { stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      [
+        "knowledge",
+        "stats",
+        "--dry-run",
+        "--index-id",
+        "idx_test",
+        "--start",
+        "2026-",
+        "--workspace-id",
+        "ws_test",
+        "--output",
+        "json",
+      ],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/Invalid time value/i);
+    // The hint should teach the accepted formats (Unix seconds / ISO date)
+    expect(stderr).toMatch(/Unix seconds|ISO date/i);
+  });
+
+  test("13 位毫秒时间戳归一化为秒级字符串", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      [
+        "knowledge",
+        "stats",
+        "--dry-run",
+        "--index-id",
+        "idx_test",
+        "--start",
+        "1785369600000", // 2026-07-30 00:00:00 UTC in milliseconds
+        "--end",
+        "1786320000000", // 2026-08-10 00:00:00 UTC in milliseconds
+        "--workspace-id",
+        "ws_test",
+        "--output",
+        "json",
+      ],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.startTimestamp).toBe("1785369600");
+    expect(data.request?.endTimestamp).toBe("1786320000");
+  });
+
+  test("缺 --index-id 报用法错误 (exit 2)", async () => {
+    const { exitCode } = await runCommandE2e(
+      KNOWLEDGE_KB_STATS_ROUTES,
+      ["knowledge", "stats", "--dry-run", "--workspace-id", "ws_test"],
+      { DASHSCOPE_API_KEY: "sk-fake-for-dryrun" },
+    );
+    expect(exitCode).toBe(2);
+  });
+});
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-kb-update.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-kb-update.e2e.test.ts
new file mode 100644
index 00000000..c528e55f
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-kb-update.e2e.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, test } from "vite-plus/test";
+import { parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_KB_UPDATE_ROUTES } from "../topic-routes.ts";
+
+describe("e2e: knowledge kb update", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--index-id/i);
+    expect(stderr).toMatch(/--name/i);
+    expect(stderr).toMatch(/--description/i);
+    expect(stderr).toMatch(/--rerank-min-score/i);
+  });
+
+  test("缺 --index-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--description",
+      "x",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("无修改项报 USAGE (2) 'Nothing to update'", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/nothing to update/i);
+  });
+
+  test("--rerank-min-score 1.5 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--rerank-min-score",
+      "1.5",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--name 21 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--name",
+      "x".repeat(21),
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 body 键名为 id (本接口坑位)", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--description",
+      "new desc",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ endpoint?: string; request?: Record<string, unknown> }>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/index\/update/);
+    expect(data.request?.id).toBe("idx_test");
+    expect(data.request).not.toHaveProperty("index_id");
+    expect(data.request?.description).toBe("new desc");
+  });
+
+  test("--dry-run 断言 rerankMinScore body 键名映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_KB_UPDATE_ROUTES, [
+      "knowledge",
+      "update",
+      "--index-id",
+      "idx_test",
+      "--rerank-min-score",
+      "0.3",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<{ request?: Record<string, unknown> }>(stdout);
+    expect(data.request?.rerankMinScore).toBe(0.3);
+  });
+});
+
+// Live coverage: the kb delete self-cleaning chain (knowledge-kb-delete.e2e.test.ts)
+// runs a live update step between create and delete.
diff --git a/packages/commands/tests/e2e/knowledge-search.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-search.e2e.test.ts
similarity index 60%
rename from packages/commands/tests/e2e/knowledge-search.e2e.test.ts
rename to packages/commands/tests/e2e/knowledge/knowledge-search.e2e.test.ts
index fdbdf477..d2979aa8 100644
--- a/packages/commands/tests/e2e/knowledge-search.e2e.test.ts
+++ b/packages/commands/tests/e2e/knowledge/knowledge-search.e2e.test.ts
@@ -1,14 +1,20 @@
 import { describe, expect, test } from "vite-plus/test";
-import { isSearchE2EReady, parseStdoutJson, runCommandE2e } from "./helpers.ts";
-import { KNOWLEDGE_SEARCH_ROUTES } from "./topic-routes.ts";
+import {
+  isMultimodalSearchE2EReady,
+  isSearchE2EReady,
+  isTableSearchE2EReady,
+  parseStdoutJson,
+  runCommandE2e,
+} from "../helpers.ts";
+import { KNOWLEDGE_SEARCH_ROUTES } from "../topic-routes.ts";
 
 interface DryRunBody {
   endpoint?: string;
   request?: {
     query?: string;
     agent_id?: string;
+    agent_version?: string;
     images?: string[];
-    query_history?: Array<{ role: string; content: string }>;
   };
 }
 
@@ -24,7 +30,6 @@ describe("e2e: knowledge search", () => {
     expect(stderr).toMatch(/--agent-id/i);
     expect(stderr).toMatch(/--workspace-id/i);
     expect(stderr).toMatch(/--image/i);
-    expect(stderr).toMatch(/--query-history/i);
   });
 
   test("缺少 --query 时报用法错误并退出 (2)", async () => {
@@ -52,7 +57,7 @@ describe("e2e: knowledge search", () => {
   test("缺少 --workspace-id 时非零退出并提示", async () => {
     const { stderr, exitCode } = await runCommandE2e(
       KNOWLEDGE_SEARCH_ROUTES,
-      // 假 key + 隔离配置目录:避免本机 config 的 workspace_id/api_key 漏入
+      // Fake key + isolated config dir: keep the local config's workspace_id/api_key from leaking in
       [
         "knowledge",
         "search",
@@ -91,76 +96,55 @@ describe("e2e: knowledge search", () => {
     expect(data.endpoint).toMatch(/api\/v1\/indices\/knowledge\/search/);
     expect(data.request?.query).toBe("什么是RAG");
     expect(data.request?.agent_id).toBe("aid_test");
+    // Without --agent-version the field is not sent (default behavior unchanged: latest published version)
+    expect(data.request).not.toHaveProperty("agent_version");
   });
 
-  test("--dry-run + --image 输出 images", async () => {
+  test("--dry-run + --agent-version 落在 body 顶层", async () => {
     const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
       "knowledge",
       "search",
       "--dry-run",
       "--query",
-      "test",
+      "什么是RAG",
       "--agent-id",
       "aid_test",
+      "--agent-version",
+      "beta",
       "--workspace-id",
       "ws_test",
-      "--image",
-      "https://example.com/a.jpg",
-      "--image",
-      "https://example.com/b.jpg",
       "--output",
       "json",
     ]);
     expect(exitCode, stderr).toBe(0);
     const data = parseStdoutJson<DryRunBody>(stdout);
-    expect(data.request?.images).toEqual([
-      "https://example.com/a.jpg",
-      "https://example.com/b.jpg",
-    ]);
+    expect(data.request?.agent_version).toBe("beta");
   });
 
-  test("--dry-run + --query-history 输出用户对话历史", async () => {
+  test("--dry-run + --image 输出 images", async () => {
     const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
       "knowledge",
       "search",
       "--dry-run",
       "--query",
-      "它怎么工作",
+      "test",
       "--agent-id",
       "aid_test",
       "--workspace-id",
       "ws_test",
-      "--query-history",
-      '[{"role":"user","content":"什么是RAG"},{"role":"assistant","content":"RAG是检索增强生成"}]',
+      "--image",
+      "https://example.com/a.jpg",
+      "--image",
+      "https://example.com/b.jpg",
       "--output",
       "json",
     ]);
     expect(exitCode, stderr).toBe(0);
     const data = parseStdoutJson<DryRunBody>(stdout);
-    expect(data.request?.query_history).toEqual([
-      { role: "user", content: "什么是RAG" },
-      { role: "assistant", content: "RAG是检索增强生成" },
-    ]);
-  });
-
-  test("--dry-run + --query-history 无效 JSON 非零退出", async () => {
-    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
-      "knowledge",
-      "search",
-      "--dry-run",
-      "--query",
-      "test",
-      "--agent-id",
-      "aid_test",
-      "--workspace-id",
-      "ws_test",
-      "--query-history",
-      "not-valid-json",
-      "--output",
-      "json",
+    expect(data.request?.images).toEqual([
+      "https://example.com/a.jpg",
+      "https://example.com/b.jpg",
     ]);
-    expect(exitCode).not.toBe(0);
-    expect(stderr).toMatch(/query-history.*valid JSON/i);
   });
 });
 
@@ -229,28 +213,6 @@ describe.skipIf(!isSearchE2EReady())("e2e: knowledge search (live)", () => {
     expect(stdout).toMatch(/\[1\].*score/);
   });
 
-  test("search with --query-history returns results", async () => {
-    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
-      "knowledge",
-      "search",
-      "--query",
-      "它怎么工作",
-      "--agent-id",
-      agentId,
-      "--workspace-id",
-      workspaceId,
-      "--query-history",
-      '[{"role":"user","content":"什么是大模型"},{"role":"assistant","content":"大模型是大规模语言模型"}]',
-      "--output",
-      "json",
-    ]);
-
-    expect(exitCode, stderr).toBe(0);
-    const data = parseStdoutJson<SearchResponse>(stdout);
-    expect(data.code).toBe("Success");
-    expect(data.data.nodes.length).toBeGreaterThan(0);
-  });
-
   test("search with invalid agent_id fails gracefully", async () => {
     const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
       "knowledge",
@@ -269,3 +231,86 @@ describe.skipIf(!isSearchE2EReady())("e2e: knowledge search (live)", () => {
     expect(stderr).toBeTruthy();
   });
 });
+
+// Long-lived console-created fixtures (multimodal / table services cannot be
+// created via the CLI — see .env BAILIAN_E2E_IMAGE_SEARCH_AGENT_ID etc.)
+describe.skipIf(!isMultimodalSearchE2EReady())(
+  "e2e: knowledge search --image live (常驻 fixture)",
+  () => {
+    const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+    const imageSearchAgentId = process.env.BAILIAN_E2E_IMAGE_SEARCH_AGENT_ID!;
+
+    test("多模态服务接受 --image 并返回 Success", async () => {
+      // Recall is not asserted: hits depend on the fixture base's image contents.
+      // The functional contract under test: the images param is accepted end-to-end.
+      const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
+        "knowledge",
+        "search",
+        "--query",
+        "图里有什么",
+        "--agent-id",
+        imageSearchAgentId,
+        "--workspace-id",
+        workspaceId,
+        "--image",
+        "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg",
+        "--output",
+        "json",
+      ]);
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<SearchResponse>(stdout);
+      expect(data.code).toBe("Success");
+      expect(Array.isArray(data.data.nodes)).toBe(true);
+    }, 60_000);
+  },
+);
+
+describe.skipIf(!isTableSearchE2EReady())(
+  "e2e: knowledge search 表格库 live (常驻 fixture)",
+  () => {
+    const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+    const tableSearchAgentId = process.env.BAILIAN_E2E_TABLE_SEARCH_AGENT_ID!;
+
+    test("表格行召回: 命中 fixture 已知单元格值", async () => {
+      // “颜色填充” is a known ZH-column cell in the fixture table (nop0ludera)
+      const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
+        "knowledge",
+        "search",
+        "--query",
+        "颜色填充",
+        "--agent-id",
+        tableSearchAgentId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(exitCode, stderr).toBe(0);
+      const data = parseStdoutJson<SearchResponse>(stdout);
+      expect(data.code).toBe("Success");
+      expect(data.data.nodes.length).toBeGreaterThan(0);
+      expect(data.data.nodes.map((node) => node.text).join("\n")).toContain("颜色填充");
+    }, 60_000);
+
+    test("--agent-version 非法版本值: 服务端拒绝并原样透传 (非零退出)", async () => {
+      // The version set is server-side state — the CLI sends the value as-is and
+      // passes the server rejection through (verified live: RagAgentNotExist)
+      const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SEARCH_ROUTES, [
+        "knowledge",
+        "search",
+        "--query",
+        "颜色填充",
+        "--agent-id",
+        tableSearchAgentId,
+        "--agent-version",
+        "not-a-version",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(exitCode).not.toBe(0);
+      expect(stderr).toMatch(/Agent application not found|RagAgentNotExist/i);
+    }, 60_000);
+  },
+);
diff --git a/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts
new file mode 100644
index 00000000..1d35d578
--- /dev/null
+++ b/packages/commands/tests/e2e/knowledge/knowledge-service.e2e.test.ts
@@ -0,0 +1,1023 @@
+// service group, 7 commands: the static group covers help/missing-args/dry-run per
+// command; the live group runs the full lifecycle (create → scalar update → get
+// assertion → search --agent-version beta smoke → deploy → copy → delete×2).
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
+import { KNOWLEDGE_SERVICE_ROUTES } from "../topic-routes.ts";
+
+interface DryRunBody {
+  endpoint?: string;
+  request?: Record<string, unknown>;
+}
+
+describe("e2e: knowledge service list", () => {
+  test("--help 展示 flags", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--help",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    expect(stderr).toMatch(/--scene/i);
+    expect(stderr).toMatch(/--status/i);
+    expect(stderr).toMatch(/--index-id/i);
+  });
+
+  test("缺 --scene 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--scene 非法值报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "qa",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--status 非法值报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "chat",
+      "--status",
+      "online",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--page-size 101 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "chat",
+      "--page-size",
+      "101",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run 断言 body agent_scene 与分页走 body", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "chat",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/api\/v1\/indices\/rag\/app\/list/);
+    expect(data.request?.agent_scene).toBe("chat");
+    expect(data.request?.pipeline_id).toBe("idx_test");
+    expect(data.request?.page_number).toBe(1);
+  });
+
+  test("--dry-run 断言 --status/--name/--agent-id 的 snake_case body 映射", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "search",
+      "--status",
+      "deployed",
+      "--name",
+      "demo",
+      "--agent-id",
+      "aid_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.request?.agent_status).toBe("deployed");
+    expect(data.request?.agent_name).toBe("demo");
+    expect(data.request?.agent_id).toBe("aid_test");
+  });
+});
+
+describe("e2e: knowledge service get / create / copy", () => {
+  test("get: 缺 --agent-id 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "get",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("get: --dry-run 断言 agent_version 透传", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "get",
+      "--agent-id",
+      "aid_test",
+      "--agent-version",
+      "beta",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/rag\/app\/get/);
+    expect(data.request?.agent_version).toBe("beta");
+  });
+
+  test("create: 缺 --scene 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      "demo",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("create: --scene 非法值报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      "demo",
+      "--scene",
+      "qa",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("create: --name 201 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      "x".repeat(201),
+      "--scene",
+      "chat",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("create: --description 1001 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      "demo",
+      "--scene",
+      "chat",
+      "--description",
+      "x".repeat(1001),
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("create: --dry-run + --index-id 断言最简 kb_search_configs", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      "demo",
+      "--scene",
+      "search",
+      "--index-id",
+      "idx_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    const agentConfig = data.request?.agent_config as
+      | { kb_search_configs?: Array<{ id: string }> }
+      | undefined;
+    expect(agentConfig?.kb_search_configs).toEqual([{ id: "idx_test" }]);
+  });
+
+  test("copy: --dry-run 断言 body agent_id", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "copy",
+      "--agent-id",
+      "aid_test",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/rag\/app\/copy/);
+    expect(data.request?.agent_id).toBe("aid_test");
+  });
+});
+
+describe("e2e: knowledge service update", () => {
+  test("无修改项报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/nothing to update/i);
+  });
+
+  test("--config-file 与标量 config flag 互斥 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--temperature",
+      "0.5",
+      "--config-file",
+      "/tmp/whatever.json",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("已发布版本 + config 修改前置拦截 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--agent-version",
+      "1",
+      "--temperature",
+      "0.5",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/beta draft/i);
+  });
+
+  test("--temperature 2.5 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--temperature",
+      "2.5",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--policy 非法值报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--policy",
+      "fast",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--max-llm-calls 31 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--max-llm-calls",
+      "31",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--enable-session-file 非 true/false 报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--enable-session-file",
+      "maybe",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--name 201 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--name",
+      "x".repeat(201),
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--description 1001 字符报 USAGE (2)", async () => {
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--description",
+      "x".repeat(1001),
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--config-file 非法 JSON 报 USAGE (2)", async () => {
+    const fixtureDir = mkdtempSync(join(tmpdir(), "svc-update-e2e-"));
+    const badJson = join(fixtureDir, "bad.json");
+    writeFileSync(badJson, "{not json");
+    const { exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--config-file",
+      badJson,
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+    ]);
+    expect(exitCode).toBe(2);
+  });
+
+  test("--dry-run + --version-desc 断言 body 与标量合并说明", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      "aid_test",
+      "--temperature",
+      "0.7",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody & { note?: string }>(stdout);
+    expect(data.endpoint).toMatch(/rag\/app\/update/);
+    const agentConfig = data.request?.agent_config as { temperature?: number } | undefined;
+    expect(agentConfig?.temperature).toBe(0.7);
+    expect(data.note).toMatch(/merged/i);
+  });
+});
+
+describe("e2e: knowledge service deploy / delete (危险)", () => {
+  test("deploy: 非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "deploy",
+      "--agent-id",
+      "aid_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+
+  test("deploy: --dry-run 断言 body", async () => {
+    const { stdout, stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "deploy",
+      "--agent-id",
+      "aid_test",
+      "--version-desc",
+      "v1 desc",
+      "--workspace-id",
+      "ws_test",
+      "--dry-run",
+      "--output",
+      "json",
+    ]);
+    expect(exitCode, stderr).toBe(0);
+    const data = parseStdoutJson<DryRunBody>(stdout);
+    expect(data.endpoint).toMatch(/rag\/app\/deploy/);
+    expect(data.request?.agent_version_desc).toBe("v1 desc");
+  });
+
+  test("delete: 非 TTY 无 --yes 报 USAGE (2)", async () => {
+    const { stderr, exitCode } = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "delete",
+      "--agent-id",
+      "aid_test",
+      "--api-key",
+      "sk-fake",
+      "--workspace-id",
+      "ws_test",
+    ]);
+    expect(exitCode).toBe(2);
+    expect(stderr).toMatch(/--yes/);
+  });
+});
+
+// Path gotcha: the actual gateway prefix is rag/app/; the rag/agent/ prefix from the
+// public API docs is not routed (it returns console HTML).
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 生命周期 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("create → update → get 断言 → deploy → copy → delete×2", async () => {
+    const serviceName = `e2e-svc-${Date.now() % 100000000}`;
+
+    // 1) create (chat scene, no knowledge base bound — verifies server defaults)
+    const createRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "create",
+      "--name",
+      serviceName,
+      "--scene",
+      "chat",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(createRun.exitCode, createRun.stderr).toBe(0);
+    const agentId = createRun.stdout.trim().split("\n").pop()!;
+    expect(agentId).toMatch(/^aid-/);
+
+    // 1.5) list asserts the new agent shows up (filtered by agent_id)
+    const listRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "list",
+      "--scene",
+      "chat",
+      "--agent-id",
+      agentId,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(listRun.exitCode, listRun.stderr).toBe(0);
+    expect(listRun.stdout.trim().split("\n")).toContain(agentId);
+
+    // 2) scalar update (read-merge-write onto the beta draft)
+    const updateRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "update",
+      "--agent-id",
+      agentId,
+      "--temperature",
+      "0.55",
+      "--workspace-id",
+      workspaceId,
+    ]);
+    expect(updateRun.exitCode, updateRun.stderr).toBe(0);
+
+    // 3) get asserts the scalars landed on beta
+    const getRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "get",
+      "--agent-id",
+      agentId,
+      "--agent-version",
+      "beta",
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(getRun.exitCode, getRun.stderr).toBe(0);
+    const getData = parseStdoutJson<{
+      data: { agent_details: Array<{ agent_config?: { temperature?: number } }> };
+    }>(getRun.stdout);
+    expect(getData.data.agent_details[0]?.agent_config?.temperature).toBe(0.55);
+
+    // 4) deploy (--yes non-interactive)
+    const deployRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "deploy",
+      "--agent-id",
+      agentId,
+      "--yes",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(deployRun.exitCode, deployRun.stderr).toBe(0);
+    expect(deployRun.stdout.trim().split("\n").pop()).toBe("1");
+
+    // 4.5) bare get (no --agent-version) returns all versions: beta draft + published 1
+    const allVersionsRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "get",
+      "--agent-id",
+      agentId,
+      "--workspace-id",
+      workspaceId,
+      "--output",
+      "json",
+    ]);
+    expect(allVersionsRun.exitCode, allVersionsRun.stderr).toBe(0);
+    const allVersionsData = parseStdoutJson<{
+      data: { agent_details: Array<{ agent_version?: string }> };
+    }>(allVersionsRun.stdout);
+    const versions = allVersionsData.data.agent_details.map((detail) => detail.agent_version);
+    expect(versions).toContain("beta");
+    expect(versions).toContain("1");
+
+    // 5) copy
+    const copyRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+      "knowledge",
+      "service",
+      "copy",
+      "--agent-id",
+      agentId,
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(copyRun.exitCode, copyRun.stderr).toBe(0);
+    const copiedAgentId = copyRun.stdout.trim().split("\n").pop()!;
+    expect(copiedAgentId).toMatch(/^aid-/);
+    expect(copiedAgentId).not.toBe(agentId);
+
+    // 6) delete both (idempotent soft delete)
+    for (const idToDelete of [copiedAgentId, agentId]) {
+      const deleteRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "delete",
+        "--agent-id",
+        idToDelete,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+    }
+
+    // 6.5) Verify both agents are gone from the server — not just that delete
+    //      returned Success, but that a fresh list filtered by agent_id finds nothing
+    for (const idToVerify of [copiedAgentId, agentId]) {
+      const postDeleteListRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "chat",
+        "--agent-id",
+        idToVerify,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(postDeleteListRun.exitCode, postDeleteListRun.stderr).toBe(0);
+      expect(postDeleteListRun.stdout.trim()).toBe("");
+    }
+  }, 300_000);
+});
+
+// Live parameter coverage: every write parameter gets a read-back assertion
+// via `service get --output json`. Read-back fields are confirmed present in
+// the get response by the existing lifecycle test and printDetail().
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (live, 自清理)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("create --description → update(name/model/policy×2/version-desc) → list(status×3/scene/name/index-id) → deploy → published update --version-desc → delete", async () => {
+    const serviceName = `e2e-svc-param-${Date.now() % 100000000}`;
+    let agentId: string | undefined;
+
+    try {
+      // ── P6: service-create --description ──
+      const createRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "create",
+        "--name",
+        serviceName,
+        "--scene",
+        "chat",
+        "--description",
+        "e2e param coverage",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(createRun.exitCode, createRun.stderr).toBe(0);
+      agentId = createRun.stdout.trim().split("\n").pop()!;
+      expect(agentId).toMatch(/^aid-/);
+
+      // get 读回验证 --description (agent_desc)
+      const createGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(createGetRun.exitCode, createGetRun.stderr).toBe(0);
+      const createGetData = parseStdoutJson<{
+        data?: { agent_desc?: string };
+      }>(createGetRun.stdout);
+      expect(createGetData.data?.agent_desc).toBe("e2e param coverage");
+
+      // ── P1: list --status draft 验证新建 agent 可见 ──
+      const listDraftRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "chat",
+        "--status",
+        "draft",
+        "--agent-id",
+        agentId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listDraftRun.exitCode, listDraftRun.stderr).toBe(0);
+      expect(listDraftRun.stdout.trim().split("\n")).toContain(agentId);
+
+      // ── P1: list --scene search (live 合法值) ──
+      const listSearchSceneRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "search",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listSearchSceneRun.exitCode, listSearchSceneRun.stderr).toBe(0);
+
+      // ── P1: list --name 精确过滤 ──
+      const listNameRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "chat",
+        "--name",
+        serviceName,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listNameRun.exitCode, listNameRun.stderr).toBe(0);
+      expect(listNameRun.stdout.trim().split("\n")).toContain(agentId);
+
+      // ── P1: list --index-id (不报错验证; 无 kb fixture) ──
+      const listIndexIdRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "search",
+        "--index-id",
+        "idx_nonexistent_e2e",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listIndexIdRun.exitCode, listIndexIdRun.stderr).toBe(0);
+
+      // ── P0 组1: update --name --version-desc --model → get 读回 3 个 scalar ──
+      const newName = `${serviceName}-renamed`;
+      const updateScalarRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "update",
+        "--agent-id",
+        agentId,
+        "--name",
+        newName,
+        "--version-desc",
+        "beta-v1",
+        "--model",
+        "qwen-plus",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(updateScalarRun.exitCode, updateScalarRun.stderr).toBe(0);
+
+      const scalarGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(scalarGetRun.exitCode, scalarGetRun.stderr).toBe(0);
+      const scalarGetData = parseStdoutJson<{
+        data?: {
+          agent_name?: string;
+          agent_details?: Array<{
+            agent_version_desc?: string;
+            agent_config?: { agent_model?: string };
+          }>;
+        };
+      }>(scalarGetRun.stdout);
+      expect(scalarGetData.data?.agent_name).toBe(newName);
+      expect(scalarGetData.data?.agent_details?.[0]?.agent_config?.agent_model).toBe("qwen-plus");
+      expect(scalarGetData.data?.agent_details?.[0]?.agent_version_desc).toBe("beta-v1");
+
+      // ── P0 组2: update --policy turbo → get 读回 ──
+      const updateTurboRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "update",
+        "--agent-id",
+        agentId,
+        "--policy",
+        "turbo",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(updateTurboRun.exitCode, updateTurboRun.stderr).toBe(0);
+
+      const turboGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(turboGetRun.exitCode, turboGetRun.stderr).toBe(0);
+      const turboData = parseStdoutJson<{
+        data?: {
+          agent_details?: Array<{
+            agent_config?: { agent_policy?: string };
+          }>;
+        };
+      }>(turboGetRun.stdout);
+      expect(turboData.data?.agent_details?.[0]?.agent_config?.agent_policy).toBe("turbo");
+
+      // ── P0 组3: update --policy agentic → get 读回 ──
+      // 注: --max-llm-calls 10 仅作为 agentic 切换的前置条件，不做读回验证
+      const updateAgenticRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "update",
+        "--agent-id",
+        agentId,
+        "--policy",
+        "agentic",
+        "--max-llm-calls",
+        "10",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(updateAgenticRun.exitCode, updateAgenticRun.stderr).toBe(0);
+
+      const agenticGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "beta",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(agenticGetRun.exitCode, agenticGetRun.stderr).toBe(0);
+      const agenticData = parseStdoutJson<{
+        data?: {
+          agent_details?: Array<{
+            agent_config?: { agent_policy?: string };
+          }>;
+        };
+      }>(agenticGetRun.stdout);
+      expect(agenticData.data?.agent_details?.[0]?.agent_config?.agent_policy).toBe("agentic");
+
+      // ── deploy → P1: list --status deployed ──
+      const deployRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "deploy",
+        "--agent-id",
+        agentId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(deployRun.exitCode, deployRun.stderr).toBe(0);
+
+      const listDeployedRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "chat",
+        "--status",
+        "deployed",
+        "--agent-id",
+        agentId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listDeployedRun.exitCode, listDeployedRun.stderr).toBe(0);
+      expect(listDeployedRun.stdout.trim().split("\n")).toContain(agentId);
+
+      // ── P0 组4: update --agent-version 1 --version-desc (published version) ──
+      const updatePublishedRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "update",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "1",
+        "--version-desc",
+        "published-v1-desc",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(updatePublishedRun.exitCode, updatePublishedRun.stderr).toBe(0);
+
+      // get --agent-version 1 读回验证 --version-desc
+      const publishedGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "get",
+        "--agent-id",
+        agentId,
+        "--agent-version",
+        "1",
+        "--workspace-id",
+        workspaceId,
+        "--output",
+        "json",
+      ]);
+      expect(publishedGetRun.exitCode, publishedGetRun.stderr).toBe(0);
+      const publishedData = parseStdoutJson<{
+        data?: {
+          agent_details?: Array<{ agent_version_desc?: string }>;
+        };
+      }>(publishedGetRun.stdout);
+      expect(publishedData.data?.agent_details?.[0]?.agent_version_desc).toBe("published-v1-desc");
+
+      // ── delete → P1: list --status deleted ──
+      const deleteRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "delete",
+        "--agent-id",
+        agentId,
+        "--yes",
+        "--workspace-id",
+        workspaceId,
+      ]);
+      expect(deleteRun.exitCode, deleteRun.stderr).toBe(0);
+
+      const listDeletedRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+        "knowledge",
+        "service",
+        "list",
+        "--scene",
+        "chat",
+        "--status",
+        "deleted",
+        "--agent-id",
+        agentId,
+        "--workspace-id",
+        workspaceId,
+        "--quiet",
+      ]);
+      expect(listDeletedRun.exitCode, listDeletedRun.stderr).toBe(0);
+      // 软验证: deleted 状态下 agent 应出现在列表中;
+      // 若服务端不返回 deleted 列表则仅验证不报错
+      if (listDeletedRun.stdout.trim()) {
+        expect(listDeletedRun.stdout.trim().split("\n")).toContain(agentId);
+      }
+    } finally {
+      // 兜底清理
+      if (agentId) {
+        await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
+          "knowledge",
+          "service",
+          "delete",
+          "--agent-id",
+          agentId,
+          "--yes",
+          "--workspace-id",
+          workspaceId,
+        ]);
+      }
+    }
+  }, 300_000);
+});
diff --git a/packages/commands/tests/e2e/knowledge.e2e.test.ts b/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts
similarity index 76%
rename from packages/commands/tests/e2e/knowledge.e2e.test.ts
rename to packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts
index cfb58d49..160a4ed6 100644
--- a/packages/commands/tests/e2e/knowledge.e2e.test.ts
+++ b/packages/commands/tests/e2e/knowledge/knowledge.e2e.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, test } from "vite-plus/test";
-import { isDashScopeE2EReady, parseStdoutJson, runCommandE2e } from "./helpers.ts";
-import { KNOWLEDGE_ROUTES } from "./topic-routes.ts";
+import {
+  isDashScopeE2EReady,
+  isKbAdminE2EReady,
+  parseStdoutJson,
+  runCommandE2e,
+} from "../helpers.ts";
+import { KNOWLEDGE_ROUTES } from "../topic-routes.ts";
 
 // ---- Types ----
 
@@ -187,3 +192,57 @@ describe("e2e: knowledge retrieve dry-run", () => {
     expect(data.request?.rerank?.[0]?.rerank_instruct).toBe("按相关性排序");
   });
 });
+
+// Live: --rerank-instruct and --top-k (deprecated) on a real index
+describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge retrieve 参数补全 (live)", () => {
+  const workspaceId = process.env.BAILIAN_WORKSPACE_ID!;
+
+  test("retrieve --rerank-instruct + --top-k (不报错验证)", async () => {
+    // Grab a real index id from the workspace
+    const listRun = await runCommandE2e(KNOWLEDGE_ROUTES, [
+      "knowledge",
+      "list",
+      "--workspace-id",
+      workspaceId,
+      "--quiet",
+    ]);
+    expect(listRun.exitCode, listRun.stderr).toBe(0);
+    const indexId = listRun.stdout.trim().split("\n")[0];
+    if (!indexId) return;
+
+    // P6: --rerank-instruct (live)
+    const rerankInstructRun = await runCommandE2e(KNOWLEDGE_ROUTES, [
+      "knowledge",
+      "retrieve",
+      "--index-id",
+      indexId,
+      "--query",
+      "e2e test",
+      "--rerank",
+      "--rerank-model",
+      "qwen3-rerank-hybrid",
+      "--rerank-mode",
+      "custom",
+      "--rerank-instruct",
+      "按相关性排序",
+      "--output",
+      "json",
+    ]);
+    expect(rerankInstructRun.exitCode, rerankInstructRun.stderr).toBe(0);
+
+    // P6: --top-k (deprecated, verify still accepted)
+    const topKRun = await runCommandE2e(KNOWLEDGE_ROUTES, [
+      "knowledge",
+      "retrieve",
+      "--index-id",
+      indexId,
+      "--query",
+      "e2e test",
+      "--top-k",
+      "10",
+      "--output",
+      "json",
+    ]);
+    expect(topKRun.exitCode, topKRun.stderr).toBe(0);
+  }, 60_000);
+});
diff --git a/packages/commands/tests/e2e/topic-routes.ts b/packages/commands/tests/e2e/topic-routes.ts
index 6df26efa..2c5363f5 100644
--- a/packages/commands/tests/e2e/topic-routes.ts
+++ b/packages/commands/tests/e2e/topic-routes.ts
@@ -39,6 +39,7 @@ export const KNOWLEDGE_ROUTES: E2eRouteExports = {
   "knowledge retrieve": "knowledgeRetrieve",
   "knowledge search": "knowledgeSearch",
   "knowledge chat": "knowledgeChat",
+  "knowledge list": "knowledgeKbList", // live: grab a real index id for retrieve
 };
 
 export const KNOWLEDGE_SEARCH_ROUTES: E2eRouteExports = {
@@ -194,3 +195,157 @@ export const MANAGED_AGENT_ROUTES: E2eRouteExports = {
   "managed-agent session send": "managedAgentSessionSend",
   "managed-agent skill-list": "managedAgentSkillList",
 };
+
+export const KNOWLEDGE_KB_LIST_ROUTES: E2eRouteExports = {
+  "knowledge list": "knowledgeKbList",
+};
+
+export const KNOWLEDGE_KB_INFO_ROUTES: E2eRouteExports = {
+  "knowledge info": "knowledgeKbInfo",
+  "knowledge list": "knowledgeKbList", // live cases list first to grab a real id
+};
+
+export const KNOWLEDGE_DOC_LIST_ROUTES: E2eRouteExports = {
+  "knowledge doc list": "knowledgeDocList",
+  "knowledge list": "knowledgeKbList", // live cases grab a real index id first
+};
+
+export const KNOWLEDGE_DOC_STATUS_ROUTES: E2eRouteExports = {
+  "knowledge doc status": "knowledgeDocStatus",
+  "knowledge doc upload": "knowledgeDocUpload", // live: produce a real job_id
+  "knowledge create": "knowledgeKbCreate", // live: create a throwaway base
+  "knowledge delete": "knowledgeKbDelete", // live: cleanup the throwaway base
+  "knowledge file delete": "knowledgeFileDelete", // live: cleanup data-center files
+};
+
+export const KNOWLEDGE_DOC_UPLOAD_ROUTES: E2eRouteExports = {
+  "knowledge doc upload": "knowledgeDocUpload",
+  "knowledge file delete": "knowledgeFileDelete", // live cleanup of data-center files
+  "knowledge list": "knowledgeKbList", // live: grab a real index id for --index-id --wait
+};
+
+export const KNOWLEDGE_KB_CREATE_ROUTES: E2eRouteExports = {
+  "knowledge create": "knowledgeKbCreate",
+};
+
+export const KNOWLEDGE_KB_UPDATE_ROUTES: E2eRouteExports = {
+  "knowledge update": "knowledgeKbUpdate",
+};
+
+export const KNOWLEDGE_KB_DELETE_ROUTES: E2eRouteExports = {
+  "knowledge delete": "knowledgeKbDelete",
+  "knowledge create": "knowledgeKbCreate", // live self-cleaning chain
+  "knowledge update": "knowledgeKbUpdate", // live update step in the chain
+  "knowledge info": "knowledgeKbInfo", // live: verify update landed on the server
+  "knowledge list": "knowledgeKbList",
+  "knowledge doc upload": "knowledgeDocUpload",
+  "knowledge doc list": "knowledgeDocList", // live: verify imported file is visible in the KB
+  "knowledge file delete": "knowledgeFileDelete", // live cleanup of data-center files
+};
+
+export const KNOWLEDGE_DOC_DELETE_ROUTES: E2eRouteExports = {
+  "knowledge doc delete": "knowledgeDocDelete",
+};
+
+export const KNOWLEDGE_DOC_TAG_ROUTES: E2eRouteExports = {
+  "knowledge doc tag": "knowledgeDocTag",
+  "knowledge doc upload": "knowledgeDocUpload", // live uploads first to grab a real fileId
+  "knowledge file get": "knowledgeFileGet", // live: verify tags landed on the server
+  "knowledge file delete": "knowledgeFileDelete", // live cleanup of data-center files
+};
+
+export const KNOWLEDGE_KB_STATS_ROUTES: E2eRouteExports = {
+  "knowledge stats": "knowledgeKbStats",
+};
+
+export const KNOWLEDGE_SERVICE_ROUTES: E2eRouteExports = {
+  "knowledge service list": "knowledgeServiceList",
+  "knowledge service get": "knowledgeServiceGet",
+  "knowledge service create": "knowledgeServiceCreate",
+  "knowledge service update": "knowledgeServiceUpdate",
+  "knowledge service deploy": "knowledgeServiceDeploy",
+  "knowledge service delete": "knowledgeServiceDelete",
+  "knowledge service copy": "knowledgeServiceCopy",
+  "knowledge search": "knowledgeSearch", // beta verification chain smoke
+};
+
+export const KNOWLEDGE_CHUNK_CATEGORY_FILE_ROUTES: E2eRouteExports = {
+  "knowledge chunk add": "knowledgeChunkAdd",
+  "knowledge chunk list": "knowledgeChunkList",
+  "knowledge chunk update": "knowledgeChunkUpdate",
+  "knowledge chunk delete": "knowledgeChunkDelete",
+  "knowledge stats": "knowledgeKbStats",
+  "knowledge retrieve": "knowledgeRetrieve", // live rerank retrieval on the throwaway base
+  "knowledge category list": "knowledgeCategoryList",
+  "knowledge category add": "knowledgeCategoryAdd",
+  "knowledge category delete": "knowledgeCategoryDelete",
+  "knowledge file list": "knowledgeFileList",
+  "knowledge file get": "knowledgeFileGet",
+  "knowledge file delete": "knowledgeFileDelete",
+  "knowledge collection create": "knowledgeCollectionCreate",
+  "knowledge collection get": "knowledgeCollectionGet",
+  "knowledge doc import-oss": "knowledgeDocImportOss",
+  "knowledge list": "knowledgeKbList", // live grabs a real index id
+  "knowledge doc list": "knowledgeDocList", // table fixture: resolve the document-level dataId
+  "knowledge doc upload": "knowledgeDocUpload", // live produces a fileId
+  "knowledge doc delete": "knowledgeDocDelete", // live verifies document-level delete semantics
+};
+
+// ---- Journey-level routes (full user-journey chains, see journeys/README.md) ----
+
+/** Minimal create/cleanup routes shared by J1–J4 */
+const JOURNEY_KB_BASE_ROUTES: E2eRouteExports = {
+  "knowledge doc upload": "knowledgeDocUpload",
+  "knowledge create": "knowledgeKbCreate",
+  "knowledge retrieve": "knowledgeRetrieve",
+  "knowledge delete": "knowledgeKbDelete",
+  "knowledge file delete": "knowledgeFileDelete", // clean up data-center files
+};
+
+export const JOURNEY_J1_ROUTES: E2eRouteExports = {
+  ...JOURNEY_KB_BASE_ROUTES,
+  "knowledge service create": "knowledgeServiceCreate",
+  "knowledge service get": "knowledgeServiceGet", // search-service retrieval-parameter backfill chain
+  "knowledge service update": "knowledgeServiceUpdate",
+  "knowledge service delete": "knowledgeServiceDelete",
+  "knowledge search": "knowledgeSearch",
+  "knowledge chat": "knowledgeChat",
+};
+
+export const JOURNEY_J2_ROUTES: E2eRouteExports = {
+  ...JOURNEY_KB_BASE_ROUTES,
+  "knowledge doc list": "knowledgeDocList",
+  "knowledge doc status": "knowledgeDocStatus",
+  "knowledge doc tag": "knowledgeDocTag",
+  "knowledge doc delete": "knowledgeDocDelete",
+  "knowledge stats": "knowledgeKbStats",
+};
+
+export const JOURNEY_J3_ROUTES: E2eRouteExports = {
+  ...JOURNEY_KB_BASE_ROUTES,
+  "knowledge chunk list": "knowledgeChunkList",
+  "knowledge chunk update": "knowledgeChunkUpdate",
+  "knowledge chunk delete": "knowledgeChunkDelete", // negative branch: delete an unknown chunk id
+};
+
+export const JOURNEY_J4_ROUTES: E2eRouteExports = {
+  ...JOURNEY_KB_BASE_ROUTES,
+  "knowledge service create": "knowledgeServiceCreate",
+  "knowledge service update": "knowledgeServiceUpdate",
+  "knowledge service get": "knowledgeServiceGet",
+  "knowledge service deploy": "knowledgeServiceDeploy",
+  "knowledge service delete": "knowledgeServiceDelete",
+  "knowledge search": "knowledgeSearch",
+};
+
+export const JOURNEY_J5_ROUTES: E2eRouteExports = {
+  "knowledge collection create": "knowledgeCollectionCreate",
+  "knowledge collection get": "knowledgeCollectionGet",
+  "knowledge category add": "knowledgeCategoryAdd",
+  "knowledge category list": "knowledgeCategoryList",
+  "knowledge category delete": "knowledgeCategoryDelete",
+  "knowledge file list": "knowledgeFileList",
+  "knowledge file get": "knowledgeFileGet",
+  "knowledge file delete": "knowledgeFileDelete",
+  "knowledge doc upload": "knowledgeDocUpload",
+};
diff --git a/packages/commands/tests/knowledge/knowledge-kb-create.test.ts b/packages/commands/tests/knowledge/knowledge-kb-create.test.ts
new file mode 100644
index 00000000..904a26f9
--- /dev/null
+++ b/packages/commands/tests/knowledge/knowledge-kb-create.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, test } from "vite-plus/test";
+import { buildDataSourceFields } from "../../src/commands/knowledge/kb-create.ts";
+
+describe("buildDataSourceFields", () => {
+  test("--doc-id 推导 DATA_CENTER_FILE + docIds", () => {
+    const fields = buildDataSourceFields({ docId: ["file_1", "file_2"] });
+    expect(fields).toEqual({
+      sourceType: "DATA_CENTER_FILE",
+      docIds: ["file_1", "file_2"],
+      dataSources: [{ sourceType: "DATA_CENTER_FILE" }],
+    });
+  });
+
+  test("--category-id 推导 DATA_CENTER_CATEGORY + categoryIds", () => {
+    const fields = buildDataSourceFields({ categoryId: ["cate_1"] });
+    expect(fields).toEqual({
+      sourceType: "DATA_CENTER_CATEGORY",
+      categoryIds: ["cate_1"],
+      dataSources: [{ sourceType: "DATA_CENTER_CATEGORY" }],
+    });
+  });
+});
diff --git a/packages/commands/tests/knowledge/knowledge-shared.test.ts b/packages/commands/tests/knowledge/knowledge-shared.test.ts
new file mode 100644
index 00000000..308631a4
--- /dev/null
+++ b/packages/commands/tests/knowledge/knowledge-shared.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vite-plus/test";
+import { ExitCode } from "bailian-cli-core";
+import { resolveWorkspaceId, truncateLine } from "../../src/commands/knowledge/shared.ts";
+
+const identity = { binName: "kscli" };
+
+describe("resolveWorkspaceId", () => {
+  test("flag 优先于 settings", () => {
+    const workspaceId = resolveWorkspaceId({
+      flags: { workspaceId: "ws_flag" },
+      settings: { workspaceId: "ws_cfg" },
+      identity,
+    });
+    expect(workspaceId).toBe("ws_flag");
+  });
+
+  test("无 flag 时回退 settings (env/config 已并入 settings)", () => {
+    const workspaceId = resolveWorkspaceId({
+      flags: {},
+      settings: { workspaceId: "ws_cfg" },
+      identity,
+    });
+    expect(workspaceId).toBe("ws_cfg");
+  });
+
+  test("均缺失时抛 USAGE 且 hint 含 binName", () => {
+    try {
+      resolveWorkspaceId({ flags: {}, settings: {}, identity });
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect((error as { exitCode: number }).exitCode).toBe(ExitCode.USAGE);
+      expect((error as { hint?: string }).hint).toMatch(/kscli config set workspace_id/);
+    }
+  });
+});
+
+describe("truncateLine", () => {
+  test("非 TTY 下不截断", () => {
+    const longLine = "x".repeat(500);
+    expect(truncateLine(longLine)).toBe(longLine);
+  });
+});
diff --git a/packages/commands/tests/knowledge/knowledge-upload-support.test.ts b/packages/commands/tests/knowledge/knowledge-upload-support.test.ts
new file mode 100644
index 00000000..d12102f5
--- /dev/null
+++ b/packages/commands/tests/knowledge/knowledge-upload-support.test.ts
@@ -0,0 +1,144 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vite-plus/test";
+import { ExitCode } from "bailian-cli-core";
+import {
+  checkUploadFile,
+  expandUploadPaths,
+  UPLOAD_FORMAT_RULES,
+} from "../../src/commands/knowledge/upload-support.ts";
+
+const fixtureDir = mkdtempSync(join(tmpdir(), "upload-support-"));
+
+function writeFixture(fileName: string, content: string): string {
+  const filePath = join(fixtureDir, fileName);
+  writeFileSync(filePath, content);
+  return filePath;
+}
+
+describe("checkUploadFile", () => {
+  test("白名单内的小文件通过且无警告", () => {
+    const filePath = writeFixture("note.md", "# hello");
+    const result = checkUploadFile(filePath);
+    expect(result.sizeBytes).toBeGreaterThan(0);
+    expect(result.warning).toBeUndefined();
+  });
+
+  test("白名单外扩展名 (.zip) 抛 USAGE 并列出支持格式", () => {
+    const filePath = writeFixture("archive.zip", "PK");
+    try {
+      checkUploadFile(filePath);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect((error as { exitCode: number }).exitCode).toBe(ExitCode.USAGE);
+      expect((error as { hint?: string }).hint).toMatch(/\.pdf/);
+    }
+  });
+
+  test("文件不存在抛 GENERAL 且 hint 含 errno", () => {
+    try {
+      checkUploadFile(join(fixtureDir, "missing.md"));
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect((error as { exitCode: number }).exitCode).toBe(ExitCode.GENERAL);
+      expect((error as { hint?: string }).hint).toMatch(/ENOENT/);
+    }
+  });
+
+  test("软限类型 (.md) 超 10MB 返回警告不拦截", () => {
+    const filePath = writeFixture("big.md", "x".repeat(11 * 1024 * 1024));
+    const result = checkUploadFile(filePath);
+    expect(result.warning).toMatch(/10 MB/);
+  });
+});
+
+describe("UPLOAD_FORMAT_RULES", () => {
+  test("硬限/软限分类符合设计表", () => {
+    expect(UPLOAD_FORMAT_RULES[".pdf"]).toEqual({ maxBytes: 150 * 1024 * 1024, enforce: "block" });
+    expect(UPLOAD_FORMAT_RULES[".png"]).toEqual({ maxBytes: 20 * 1024 * 1024, enforce: "block" });
+    expect(UPLOAD_FORMAT_RULES[".xlsx"]).toEqual({ maxBytes: 10 * 1024 * 1024, enforce: "warn" });
+    expect(UPLOAD_FORMAT_RULES[".csv"]).toBeDefined(); // inconsistent across public docs; kept in the allowlist
+  });
+});
+
+describe("expandUploadPaths", () => {
+  const expandFixtureDir = mkdtempSync(join(tmpdir(), "expand-upload-"));
+
+  function setupExpandFixtures(): void {
+    // Root-level files
+    writeFileSync(join(expandFixtureDir, "readme.md"), "# root");
+    writeFileSync(join(expandFixtureDir, "data.csv"), "a,b,c");
+    writeFileSync(join(expandFixtureDir, "config.json"), "{}"); // unsupported
+    writeFileSync(join(expandFixtureDir, "script.py"), "print(1)"); // unsupported
+
+    // Subdirectory with files
+    const subDir = join(expandFixtureDir, "subdir");
+    mkdirSync(subDir);
+    writeFileSync(join(subDir, "notes.txt"), "hello");
+    writeFileSync(join(subDir, "archive.zip"), "PK"); // unsupported
+
+    // node_modules should be ignored
+    const nodeModulesDir = join(expandFixtureDir, "node_modules");
+    mkdirSync(nodeModulesDir);
+    writeFileSync(join(nodeModulesDir, "index.js"), "module.exports = {}");
+
+    // .git should be ignored
+    const gitDir = join(expandFixtureDir, ".git");
+    mkdirSync(gitDir);
+    writeFileSync(join(gitDir, "HEAD"), "ref: refs/heads/main");
+  }
+
+  setupExpandFixtures();
+
+  test("目录递归扫描: 支持的文件收集, 不支持的跳过, 忽略目录不进入", () => {
+    const result = expandUploadPaths([expandFixtureDir]);
+    const fileNames = result.files.map((filePath) => filePath.split("/").pop());
+    const skippedNames = result.skipped.map((filePath) => filePath.split("/").pop());
+
+    expect(fileNames).toContain("readme.md");
+    expect(fileNames).toContain("data.csv");
+    expect(fileNames).toContain("notes.txt");
+    // Unsupported files in root and subdir
+    expect(skippedNames).toContain("config.json");
+    expect(skippedNames).toContain("script.py");
+    expect(skippedNames).toContain("archive.zip");
+    // node_modules and .git contents should NOT appear
+    expect(fileNames).not.toContain("index.js");
+    expect(skippedNames).not.toContain("index.js");
+    expect(fileNames).not.toContain("HEAD");
+    expect(skippedNames).not.toContain("HEAD");
+  });
+
+  test("单个文件路径直接返回", () => {
+    const filePath = join(expandFixtureDir, "readme.md");
+    const result = expandUploadPaths([filePath]);
+    expect(result.files).toEqual([filePath]);
+    expect(result.skipped).toEqual([]);
+  });
+
+  test("混合文件和目录路径", () => {
+    const filePath = join(expandFixtureDir, "readme.md");
+    const result = expandUploadPaths([filePath, expandFixtureDir]);
+    // readme.md appears once from the direct file, once from the directory scan
+    const mdCount = result.files.filter((path) => path.endsWith("readme.md")).length;
+    expect(mdCount).toBe(2);
+  });
+
+  test("空目录返回空数组", () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), "empty-upload-"));
+    const result = expandUploadPaths([emptyDir]);
+    expect(result.files).toEqual([]);
+    expect(result.skipped).toEqual([]);
+  });
+
+  test("不存在的路径抛 GENERAL 且 hint 含 errno", () => {
+    try {
+      expandUploadPaths([join(expandFixtureDir, "nonexistent.md")]);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect((error as { exitCode: number }).exitCode).toBe(ExitCode.GENERAL);
+      expect((error as { hint?: string }).hint).toMatch(/ENOENT/);
+    }
+  });
+});
diff --git a/packages/core/package.json b/packages/core/package.json
index bf4e5aa8..09208945 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-core",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Core SDK for bailian-cli. See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {
diff --git a/packages/core/src/client/endpoints.ts b/packages/core/src/client/endpoints.ts
index 8ec1d307..243dda2a 100644
--- a/packages/core/src/client/endpoints.ts
+++ b/packages/core/src/client/endpoints.ts
@@ -212,3 +212,52 @@ export function deploymentUpdatePath(deployedModel: string): string {
 export function deploymentsModelsPath(): string {
   return "/api/v1/deployments/models";
 }
+
+// ---- RAG admin plane (knowledge base / data center / service management, workspace-based host) ----
+// All admin endpoints go through this factory; path constants are centralized in
+// RAG_PATHS to avoid per-endpoint boilerplate.
+
+export function ragEndpoint(workspaceId: string, path: string): string {
+  return `https://${workspaceId}.cn-beijing.maas.aliyuncs.com${path}`;
+}
+
+export const RAG_PATHS = {
+  // indices domain — knowledge bases / documents / chunks / import jobs.
+  // Note: parameter naming is inconsistent across endpoints; see per-path comments.
+  indexList: "/api/v1/indices/rag/index/list", // GET, pagination/filters go in the query string
+  indexCreateV2: "/api/v1/indices/rag/index/create_v2", // POST
+  indexUpdate: "/api/v1/indices/rag/index/update", // POST, index id parameter is named `id`
+  indexDelete: "/api/v1/indices/rag/index/delete", // POST, body { index_id }
+  indexMonitor: "/api/v1/indices/rag/index/monitor", // POST, second-precision string timestamps
+  indexFiles: "/api/v1/indices/rag/index/files", // GET, page parameter is page_num
+  indexDeleteFile: "/api/v1/indices/rag/index/delete_file", // POST, body { index_id, doc_ids }
+  indexJobCreate: "/api/v1/indices/rag/index/job/create", // POST, body requires nested dataSource { sourceType, fileIds } (flat documentIds from the docs is rejected)
+  indexJobStatus: "/api/v1/indices/rag/index_job/status", // GET, both index_id and job_id required
+  chunkList: "/api/v1/indices/rag/index/chunklist", // POST, body pageNum/pageSize
+  chunkCreate: "/api/v1/indices/rag/index/chunk/create", // POST, parameter is pipelineId; rate limit 10 req/s, no chunk_id in response
+  chunkUpdate: "/api/v1/indices/rag/index/chunk/update", // POST, parameter is pipelineId
+  chunkDelete: "/api/v1/indices/rag/index/chunk/delete", // POST, at most 10 per request
+  // agent domain — retrieval / chat services. The actual gateway prefix is rag/app/,
+  // not rag/agent/ as the public API docs state — the wrong path returns console HTML
+  // instead of an API response.
+  agentList: "/api/v1/indices/rag/app/list", // POST, agent_scene required
+  agentGet: "/api/v1/indices/rag/app/get", // POST
+  agentCreate: "/api/v1/indices/rag/app/create", // POST
+  agentUpdate: "/api/v1/indices/rag/app/update", // POST, config is only mutable on the beta draft
+  agentDeploy: "/api/v1/indices/rag/app/deploy", // POST
+  agentDelete: "/api/v1/indices/rag/app/delete", // POST, idempotent soft delete
+  agentCopy: "/api/v1/indices/rag/app/copy", // POST
+  // connector domain — data center (responses use requestId; cursor pagination via nextToken/maxResult)
+  applyFileUploadLease: "/api/v1/connector/dash/applyFileUploadLease", // sizeBytes must be a string
+  addFile: "/api/v1/connector/dash/addFile",
+  addFilesFromAuthorizedOss: "/api/v1/connector/dash/addFilesFromAuthorizedOss",
+  batchUpdateFileTag: "/api/v1/connector/dash/batchUpdateFileTag",
+  listFile: "/api/v1/connector/dash/listFile", // categoryId required
+  describeFile: "/api/v1/connector/dash/describeFile",
+  deleteFile: "/api/v1/connector/dash/deleteFile",
+  addConnector: "/api/v1/connector/dash/addConnector",
+  getConnector: "/api/v1/connector/dash/getConnector",
+  listCategory: "/api/v1/connector/dash/listCategory", // note: maxResult is singular
+  addCategory: "/api/v1/connector/dash/addCategory",
+  deleteCategory: "/api/v1/connector/dash/deleteCategory",
+} as const;
diff --git a/packages/core/src/client/headers.ts b/packages/core/src/client/headers.ts
index 9d84d396..5f8d30e9 100644
--- a/packages/core/src/client/headers.ts
+++ b/packages/core/src/client/headers.ts
@@ -1,15 +1,19 @@
 /**
  * Shared HTTP request headers for all outgoing requests.
  *
- * Centralises the `x-dashscope-source-config` header so Bailian/DashScope API
- * transports use the same product identity. Generic npm, OSS, and result-file
- * transfers deliberately do not send this gateway-consumed metadata.
+ * Centralises the `x-dashscope-source-config` and `x-dashscope-openapisource`
+ * headers so Bailian/DashScope API transports use the same product identity.
+ * Generic npm, OSS, and result-file transfers deliberately do not send this
+ * gateway-consumed metadata.
  */
 
 import type { Identity } from "../config/schema.ts";
 
 export const CHANNEL = "bailian-cli";
 
+/** Static source identifier advertised to the DashScope/Bailian OpenAPI gateway. */
+export const OPEN_API_SOURCE = "BailianCLI";
+
 export type TrackingIdentity = Pick<Identity, "binName" | "version">;
 
 export function sourceConfig(identity: TrackingIdentity): string {
@@ -27,5 +31,6 @@ export function sourceConfig(identity: TrackingIdentity): string {
 export function trackingHeaders(identity: TrackingIdentity): Record<string, string> {
   return {
     "x-dashscope-source-config": sourceConfig(identity),
+    "x-dashscope-openapisource": OPEN_API_SOURCE,
   };
 }
diff --git a/packages/core/src/client/index.ts b/packages/core/src/client/index.ts
index 5164e477..bd34921c 100644
--- a/packages/core/src/client/index.ts
+++ b/packages/core/src/client/index.ts
@@ -16,6 +16,8 @@ export {
   modelsLimitsPath,
   modelsPermissionsPath,
   profileSchemaPath,
+  ragEndpoint,
+  RAG_PATHS,
   responsesPath,
   speechRecognizePath,
   speechSynthesizePath,
@@ -49,7 +51,13 @@ export {
   type AsrFlashFamily,
   type BuildAsrFlashRequestOpts,
 } from "./asr-routes.ts";
-export { CHANNEL, sourceConfig, trackingHeaders, type TrackingIdentity } from "./headers.ts";
+export {
+  CHANNEL,
+  OPEN_API_SOURCE,
+  sourceConfig,
+  trackingHeaders,
+  type TrackingIdentity,
+} from "./headers.ts";
 export type { HttpDeps, RequestOpts } from "./http.ts";
 export { request, requestJson } from "./http.ts";
 export { createInstrumentedFetch, type FetchImplementation } from "./instrumented-fetch.ts";
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 0a5c0999..6537723b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -3,6 +3,7 @@ export { mapApiError, type ApiErrorBody } from "./errors/api.ts";
 export { ExitCode } from "./errors/codes.ts";
 
 export type * from "./types/api.ts";
+export type * from "./types/knowledge-admin.ts";
 export * from "./auth/index.ts";
 export * from "./client/index.ts";
 export * from "./console/index.ts";
diff --git a/packages/core/src/types/api.ts b/packages/core/src/types/api.ts
index fdc337ea..e0982fc6 100644
--- a/packages/core/src/types/api.ts
+++ b/packages/core/src/types/api.ts
@@ -449,8 +449,9 @@ export interface DashScopeKnowledgeRetrieveResponse {
 export interface KnowledgeSearchRequest {
   query: string;
   agent_id: string;
+  /** "beta" targets the debug draft; a numeric version targets that published version; defaults to the latest published version */
+  agent_version?: string;
   images?: string[];
-  query_history?: Array<{ role: "user" | "assistant"; content: string }>;
 }
 
 export interface KnowledgeSearchResponse {
@@ -499,6 +500,8 @@ export interface KnowledgeChatRequest {
   parameters: {
     agent_options: {
       agent_id: string;
+      /** "beta" targets the debug draft; a numeric version targets that published version; defaults to the latest published version */
+      agent_version?: string;
       user?: {
         user_id?: string;
         workspace_id?: string;
diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts
index bf547792..35b46978 100644
--- a/packages/core/src/types/index.ts
+++ b/packages/core/src/types/index.ts
@@ -80,3 +80,4 @@ export type {
   StreamChunk,
   UserProfileResponse,
 } from "./api.ts";
+export type * from "./knowledge-admin.ts";
diff --git a/packages/core/src/types/knowledge-admin.ts b/packages/core/src/types/knowledge-admin.ts
new file mode 100644
index 00000000..32107821
--- /dev/null
+++ b/packages/core/src/types/knowledge-admin.ts
@@ -0,0 +1,350 @@
+// Types for the RAG admin plane (indices / agent / connector domains). Modeled
+// after the raw API field names — the mix of snake_case and camelCase reflects
+// the server as-is and is intentionally NOT normalized here; normalization only
+// happens at the CLI output layer. Kept separate from api.ts to avoid bloating it.
+
+/** Common response envelope for the indices domain (top-level fields are snake_case) */
+export interface RagResponse<T> {
+  code?: string;
+  message?: string;
+  status_code?: number;
+  request_id?: string;
+  data: T;
+  [key: string]: unknown;
+}
+
+/** GET index/list row (fields inside rows are camelCase as-is; full config field set) */
+export interface RagIndexRow {
+  id: string;
+  name: string;
+  description?: string;
+  dataType?: string;
+  embeddingModelName?: string;
+  embeddingDimension?: number;
+  chunkSize?: number;
+  overlapSize?: number;
+  chunkMode?: string;
+  separator?: string;
+  rerankModelName?: string;
+  rerankMinScore?: number;
+  rerankTopN?: number;
+  rerankMode?: string;
+  enableRewrite?: boolean;
+  denseSimilarityTopK?: number;
+  sparseSimilarityTopK?: number;
+  sourceType?: string;
+  connectorId?: string;
+  [key: string]: unknown;
+}
+
+export interface RagIndexListData {
+  rows?: RagIndexRow[];
+  total?: number;
+  [key: string]: unknown;
+}
+export type RagIndexListResponse = RagResponse<RagIndexListData>;
+
+/** GET index/files document row */
+export interface RagIndexFileRow {
+  doc_id?: string;
+  doc_name?: string;
+  doc_type?: string;
+  status?: string;
+  size?: number | string;
+  ingestion_id?: string;
+  [key: string]: unknown;
+}
+export interface RagIndexFilesData {
+  rows?: RagIndexFileRow[];
+  total_count?: number;
+  [key: string]: unknown;
+}
+export type RagIndexFilesResponse = RagResponse<RagIndexFilesData>;
+
+/**
+ * GET index_job/status (verified against the live API)
+ * Gotcha: the overall job state lives in `ingestion_status` (PENDING/RUNNING/COMPLETED,
+ * no FAILED value); the per-document list is `rows[]` (not docs[]), and failures
+ * surface via `rows[].code` (e.g. PARSE_FAILED).
+ */
+export interface RagIndexJobDoc {
+  doc_id?: string;
+  doc_name?: string;
+  doc_type?: string;
+  /** Fine-grained processing status code: FINISH / PARSE_FAILED / ... */
+  code?: string;
+  status?: string;
+  message?: string;
+  size?: number | string;
+  ingestion_id?: string;
+  [key: string]: unknown;
+}
+export interface RagIndexJobStatusData {
+  /** Overall job state: PENDING / RUNNING / COMPLETED */
+  ingestion_status?: string;
+  ingestion_message?: string;
+  rows?: RagIndexJobDoc[];
+  total_count?: number;
+  [key: string]: unknown;
+}
+export type RagIndexJobStatusResponse = RagResponse<RagIndexJobStatusData>;
+
+/** Common response envelope for the connector domain (top-level requestId is camelCase — unlike the indices domain) */
+export interface RagConnectorResponse<T> {
+  code?: string;
+  message?: string;
+  requestId?: string;
+  success?: boolean;
+  status?: number | string;
+  data: T;
+  [key: string]: unknown;
+}
+
+/** POST applyFileUploadLease */
+export interface RagUploadLeaseParam {
+  url?: string;
+  method?: string;
+  headers?: Record<string, string>;
+  [key: string]: unknown;
+}
+export interface RagUploadLeaseData {
+  type?: string;
+  leaseId?: string;
+  param?: RagUploadLeaseParam;
+  [key: string]: unknown;
+}
+export type RagUploadLeaseResponse = RagConnectorResponse<RagUploadLeaseData>;
+
+/** POST addFile */
+export interface RagAddFileData {
+  fileId?: string;
+  parser?: string;
+  [key: string]: unknown;
+}
+export type RagAddFileResponse = RagConnectorResponse<RagAddFileData>;
+
+/** POST listCategory */
+export interface RagCategory {
+  categoryId?: string;
+  categoryName?: string;
+  isDefault?: boolean;
+  [key: string]: unknown;
+}
+export interface RagListCategoryData {
+  categoryList?: RagCategory[];
+  nextToken?: string;
+  [key: string]: unknown;
+}
+export type RagListCategoryResponse = RagConnectorResponse<RagListCategoryData>;
+
+/** POST index/job/create (incremental import; response field names pending live verification) */
+export interface RagJobCreateData {
+  ingestionId?: string;
+  [key: string]: unknown;
+}
+export type RagJobCreateResponse = RagResponse<RagJobCreateData>;
+
+/** POST index/create_v2 */
+export interface RagCreateIndexV2Data {
+  pipelineId?: string;
+  ingestionId?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+export type RagCreateIndexV2Response = RagResponse<RagCreateIndexV2Data>;
+
+/** POST index/update and index/delete — data carries no details (empty object or absent) */
+export type RagMutationResponse = RagResponse<Record<string, unknown> | undefined>;
+
+/** POST index/delete_file — data.deleted lists the document IDs actually deleted */
+export interface RagDeleteFileData {
+  deleted?: string[];
+  [key: string]: unknown;
+}
+export type RagDeleteFileResponse = RagResponse<RagDeleteFileData>;
+
+/** POST batchUpdateFileTag — connector-domain envelope, data is an empty object */
+export type RagBatchUpdateTagResponse = RagConnectorResponse<Record<string, unknown> | undefined>;
+
+// ---- agent domain (retrieval / chat service management) ----
+// Parameters are snake_case; responses use the indices-domain envelope.
+// Time fields are loosely modeled as string | number (live samples show
+// millisecond timestamps; tighten once verified).
+
+/** agent_config — chat and search scenes carry different field sets; modeled loosely as one type */
+export interface RagAgentConfig {
+  agent_policy?: string;
+  agent_model?: string;
+  enable_session_file?: string;
+  enable_refusal?: string;
+  enable_anti_leak?: string;
+  enable_rich_text?: string;
+  enable_citation?: string;
+  temperature?: number;
+  max_num_llm_calls?: number;
+  max_completion_tokens?: number;
+  session_file_max_parse_length?: number;
+  enable_kb_router?: string;
+  kb_router_model?: string;
+  rerank_top_n?: number;
+  hybrid_rerank?: Record<string, unknown>;
+  kb_search_configs?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+/** agent/list row */
+export interface RagAgentRow {
+  agent_id?: string;
+  agent_name?: string;
+  agent_scene?: string;
+  agent_status?: string;
+  agent_version?: string;
+  create_time?: string | number;
+  modify_time?: string | number;
+  pipeline_list?: Array<{ pipeline_id?: string; pipeline_name?: string }>;
+  [key: string]: unknown;
+}
+export interface RagAgentListData {
+  page_number?: number;
+  page_size?: number;
+  total_count?: number;
+  rows?: RagAgentRow[];
+  [key: string]: unknown;
+}
+export type RagAgentListResponse = RagResponse<RagAgentListData>;
+
+/** agent/get per-version detail */
+export interface RagAgentDetail {
+  agent_version?: string;
+  agent_version_desc?: string | null;
+  publish_time?: string | number;
+  agent_config?: RagAgentConfig;
+  [key: string]: unknown;
+}
+export interface RagAgentGetData {
+  agent_id?: string;
+  agent_name?: string;
+  agent_desc?: string;
+  agent_scene?: string;
+  agent_status?: string;
+  create_time?: string | number;
+  modify_time?: string | number;
+  agent_details?: RagAgentDetail[];
+  [key: string]: unknown;
+}
+export type RagAgentGetResponse = RagResponse<RagAgentGetData>;
+
+/** agent/create · update · deploy · delete · copy — union of the data field sets */
+export interface RagAgentMutationData {
+  agent_id?: string;
+  agent_name?: string;
+  agent_version?: string;
+  agent_status?: string;
+  [key: string]: unknown;
+}
+export type RagAgentMutationResponse = RagResponse<RagAgentMutationData>;
+
+// ---- chunk / monitor / category / file / connector / oss-import ----
+
+/** POST index/chunklist — nodes[].metadata carries the chunk payload */
+export interface RagChunkNodeMetadata {
+  _id?: string;
+  doc_id?: string;
+  doc_name?: string;
+  title?: string;
+  content?: string;
+  hier_title?: string;
+  is_displayed_chunk_content?: boolean;
+  _chunk_status_message?: string;
+  [key: string]: unknown;
+}
+export interface RagChunkNode {
+  score?: number;
+  text?: string;
+  metadata?: RagChunkNodeMetadata;
+  [key: string]: unknown;
+}
+export interface RagChunkListData {
+  total?: number;
+  nodes?: RagChunkNode[];
+  [key: string]: unknown;
+}
+export type RagChunkListResponse = RagResponse<RagChunkListData>;
+
+/** POST index/monitor — timestamps are second-precision strings.
+ * Shape verified against the live API: both monitor fields are objects,
+ * not arrays as the public docs' empty-array examples suggest. */
+export interface RagStorageMonitorData {
+  indexStorageLimit?: number;
+  indexStorageUsage?: number;
+  [key: string]: unknown;
+}
+export interface RagQpsMonitorData {
+  peakQps?: number;
+  monitorData?: Array<Record<string, unknown>>;
+  [key: string]: unknown;
+}
+export interface RagMonitorData {
+  pipelineCommercialType?: string;
+  storageMonitorData?: RagStorageMonitorData;
+  qpsMonitorData?: RagQpsMonitorData;
+  [key: string]: unknown;
+}
+export type RagMonitorResponse = RagResponse<RagMonitorData>;
+
+/** POST addCategory */
+export interface RagAddCategoryData {
+  categoryId?: string;
+  [key: string]: unknown;
+}
+export type RagAddCategoryResponse = RagConnectorResponse<RagAddCategoryData>;
+
+/** POST listFile / describeFile — field names verified against the live API:
+ * sizeBytes/uploadTime/category (not sizeInBytes/createTime/categoryId as the public docs state) */
+export interface RagDataCenterFile {
+  fileId?: string;
+  fileName?: string;
+  fileType?: string;
+  parser?: string;
+  sizeBytes?: number | string;
+  md5?: string;
+  status?: string;
+  tags?: string[] | string;
+  category?: string;
+  uploadTime?: string;
+  parseErrorMessage?: string;
+  [key: string]: unknown;
+}
+export interface RagListFileData {
+  fileList?: RagDataCenterFile[];
+  nextToken?: string;
+  hasNext?: boolean;
+  [key: string]: unknown;
+}
+export type RagListFileResponse = RagConnectorResponse<RagListFileData>;
+export type RagDescribeFileResponse = RagConnectorResponse<RagDataCenterFile>;
+
+/** POST addConnector response / getConnector response — server does NOT echo fileConnectorConfig (live-verified) */
+export interface RagConnectorInfo {
+  connectorId?: string;
+  connectorName?: string;
+  description?: string;
+  connectorType?: string;
+  [key: string]: unknown;
+}
+export type RagAddConnectorResponse = RagConnectorResponse<RagConnectorInfo>;
+export type RagGetConnectorResponse = RagConnectorResponse<RagConnectorInfo>;
+
+/** POST addFilesFromAuthorizedOss — live shape is addFileResultList (the docs' fileIds is not returned) */
+export interface RagOssImportFileResult {
+  fileId?: string;
+  ossKey?: string;
+  status?: string;
+  msg?: string;
+  [key: string]: unknown;
+}
+export interface RagOssImportData {
+  addFileResultList?: RagOssImportFileResult[];
+  [key: string]: unknown;
+}
+export type RagOssImportResponse = RagConnectorResponse<RagOssImportData>;
diff --git a/packages/core/tests/instrumented-fetch.test.ts b/packages/core/tests/instrumented-fetch.test.ts
index ccecf99b..51eb1800 100644
--- a/packages/core/tests/instrumented-fetch.test.ts
+++ b/packages/core/tests/instrumented-fetch.test.ts
@@ -57,6 +57,7 @@ test("adds UA and tracking header on Alibaba Cloud hosts", async () => {
       tags: { t1: "public", t2: "bl", t3: "1.2.3" },
     }),
   );
+  expect(headers.get("x-dashscope-openapisource")).toBe("BailianCLI");
   expect(headers.get("authorization")).toBe("Bearer k");
 });
 
@@ -66,6 +67,7 @@ test("adds UA but no tracking header on third-party hosts", async () => {
   });
   expect(headers.get("user-agent")).toBe("bailian-cli/1.2.3");
   expect(headers.get("x-dashscope-source-config")).toBeNull();
+  expect(headers.get("x-dashscope-openapisource")).toBeNull();
 });
 
 test("does not override a caller-provided User-Agent", async () => {
@@ -86,6 +88,7 @@ test("passes non-URL-parseable inputs through without tracking headers", async (
   const { url, headers } = await capture("/relative/path");
   expect(url).toBe("/relative/path");
   expect(headers.get("x-dashscope-source-config")).toBeNull();
+  expect(headers.get("x-dashscope-openapisource")).toBeNull();
 });
 
 test("uses kscli identity and version in source config", () => {
diff --git a/packages/core/tests/rag-endpoints.test.ts b/packages/core/tests/rag-endpoints.test.ts
new file mode 100644
index 00000000..c05c6a12
--- /dev/null
+++ b/packages/core/tests/rag-endpoints.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, test } from "vite-plus/test";
+import { ragEndpoint, RAG_PATHS } from "../src/client/endpoints.ts";
+
+describe("ragEndpoint", () => {
+  test("拼接 workspace 子域名与路径", () => {
+    expect(ragEndpoint("ws_test", RAG_PATHS.indexList)).toBe(
+      "https://ws_test.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/list",
+    );
+  });
+
+  test("RAG_PATHS 覆盖全部管理端点域", () => {
+    // indices domain
+    expect(RAG_PATHS.indexCreateV2).toBe("/api/v1/indices/rag/index/create_v2");
+    expect(RAG_PATHS.indexJobStatus).toBe("/api/v1/indices/rag/index_job/status");
+    expect(RAG_PATHS.chunkList).toBe("/api/v1/indices/rag/index/chunklist");
+    expect(RAG_PATHS.chunkCreate).toBe("/api/v1/indices/rag/index/chunk/create");
+    // agent domain (the actual gateway prefix is rag/app/, not rag/agent/ as the public docs state)
+    expect(RAG_PATHS.agentList).toBe("/api/v1/indices/rag/app/list");
+    // connector domain
+    expect(RAG_PATHS.listCategory).toBe("/api/v1/connector/dash/listCategory");
+  });
+});
diff --git a/packages/e2e/src/gating.ts b/packages/e2e/src/gating.ts
index a10c8596..c70dadce 100644
--- a/packages/e2e/src/gating.ts
+++ b/packages/e2e/src/gating.ts
@@ -63,3 +63,52 @@ export function isChatE2EReady(): boolean {
     !!process.env.BAILIAN_E2E_CHAT_AGENT_ID?.trim() && !!process.env.BAILIAN_WORKSPACE_ID?.trim()
   );
 }
+
+/** Knowledge admin commands (kb/doc/chunk/service/category/file) E2E readiness */
+export function isKbAdminE2EReady(): boolean {
+  if (!isDashScopeE2EReady()) return false;
+  return !!process.env.BAILIAN_WORKSPACE_ID?.trim();
+}
+
+/** connector has no delete API, so live artifacts cannot be cleaned up — only enable explicitly for a full manual regression */
+export function isConnectorE2EReady(): boolean {
+  return isKbAdminE2EReady() && process.env.BAILIAN_E2E_CONNECTOR === "1";
+}
+
+// ---- Long-lived knowledge fixtures (created manually in the console; the CLI
+// cannot create table/image-type bases or multimodal services itself) ----
+
+/** 表格型知识库 fixture（chunk --field live 闭环） */
+export function isTableKbE2EReady(): boolean {
+  return isKbAdminE2EReady() && !!process.env.BAILIAN_E2E_TABLE_INDEX_ID?.trim();
+}
+
+/** 图片型知识库 fixture（图片 chunk 回读） */
+export function isImageKbE2EReady(): boolean {
+  return isKbAdminE2EReady() && !!process.env.BAILIAN_E2E_IMAGE_INDEX_ID?.trim();
+}
+
+/** 多模态检索服务 fixture（search --image live） */
+export function isMultimodalSearchE2EReady(): boolean {
+  return isKbAdminE2EReady() && !!process.env.BAILIAN_E2E_IMAGE_SEARCH_AGENT_ID?.trim();
+}
+
+/** 多模态问答服务 fixture（chat --image live） */
+export function isMultimodalChatE2EReady(): boolean {
+  return isKbAdminE2EReady() && !!process.env.BAILIAN_E2E_IMAGE_CHAT_AGENT_ID?.trim();
+}
+
+/** 表格库检索服务 fixture（表格行召回 live） */
+export function isTableSearchE2EReady(): boolean {
+  return isKbAdminE2EReady() && !!process.env.BAILIAN_E2E_TABLE_SEARCH_AGENT_ID?.trim();
+}
+
+/** 已授权 OSS bucket fixture（doc import-oss live；需提前在 RAM 授权并放好固定测试文件） */
+export function isOssImportE2EReady(): boolean {
+  return (
+    isKbAdminE2EReady() &&
+    !!process.env.BAILIAN_E2E_OSS_BUCKET?.trim() &&
+    !!process.env.BAILIAN_E2E_OSS_REGION?.trim() &&
+    !!process.env.BAILIAN_E2E_OSS_KEY?.trim()
+  );
+}
diff --git a/packages/kscli/.gitignore b/packages/kscli/.gitignore
index 75352116..b862046e 100644
--- a/packages/kscli/.gitignore
+++ b/packages/kscli/.gitignore
@@ -2,3 +2,4 @@ node_modules
 dist
 *.log
 .DS_Store
+docs
\ No newline at end of file
diff --git a/packages/kscli/README.md b/packages/kscli/README.md
index 0df189ec..76e4c8e3 100644
--- a/packages/kscli/README.md
+++ b/packages/kscli/README.md
@@ -9,13 +9,24 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-[Knowledge Studio Console](https://rag.console.aliyun.com/) · [中文文档](README.zh.md) · [API Documentation](https://help.aliyun.com/zh/model-studio/)
+[Knowledge Studio Console](https://rag.console.aliyun.com/) · [中文文档](README.zh.md) · [API Documentation](https://help.aliyun.com/zh/model-studio/) · [Full CLI Guide](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md)
 
 </div>
 
 ## What is this?
 
-`kscli` is a standalone CLI for **knowledge-base retrieval** on Aliyun Model Studio (DashScope), purpose-built for RAG (Retrieval-Augmented Generation) workflows.
+`kscli` is a standalone CLI for **knowledge-base retrieval** on Aliyun Model Studio (DashScope), purpose-built for RAG (Retrieval-Augmented Generation) workflows. It covers the full lifecycle of knowledge bases — from creation and document ingestion to semantic search and conversational Q&A.
+
+## Features
+
+- **Knowledge base management** — Create, update, delete, and inspect knowledge bases; view storage and document statistics
+- **Document management** — Upload files, import from OSS, track processing status, tag, and delete documents
+- **Retrieval services** — Create, configure, deploy, copy, and manage retrieval services that bind knowledge bases to specific models
+- **Chunk management** — Add, list, update, and delete text chunks within documents for fine-grained content control
+- **Data center** — Manage standalone files in the workspace data center before attaching them to knowledge bases
+- **Collections & categories** — Organize knowledge bases with collections and categorize documents for scoped retrieval
+- **RAG retrieval & chat** — Semantic search across knowledge bases and streaming Q&A with grounded answers
+- **Agent-friendly** — Structured JSON output (`--output json`), dry-run mode (`--dry-run`), and quiet mode (`--quiet`) for scripting
 
 ## Installation
 
@@ -28,13 +39,31 @@ npm install -g knowledge-studio-cli
 ## Quick Start
 
 ```bash
-# Search a knowledge base
+# 1. Create a knowledge base
+kscli kb create \
+  --name "my-kb" \
+  --embedding-model text-embedding-v3 \
+  --workspace-id <your-workspace-id>
+
+# 2. Upload a document
+kscli doc upload \
+  --kb-id <kb-id> \
+  --file ./product-docs.pdf \
+  --workspace-id <your-workspace-id>
+
+# 3. Check processing status
+kscli doc status \
+  --kb-id <kb-id> \
+  --doc-id <doc-id> \
+  --workspace-id <your-workspace-id>
+
+# 4. Semantic search
 kscli search \
   --query "What is Model Studio?" \
   --agent-id <your-agent-id> \
   --workspace-id <your-workspace-id>
 
-# Chat with a knowledge base
+# 5. Knowledge-base Q&A (streaming)
 kscli chat \
   --message "What is RAG?" \
   --agent-id <your-agent-id> \
@@ -43,14 +72,84 @@ kscli chat \
 
 ## Commands
 
-| Command       | Description                                       |
-| :------------ | :------------------------------------------------ |
-| `search`      | Semantic search across knowledge bases (RAG)      |
-| `chat`        | Knowledge-base Q&A with streaming (RAG)           |
-| `retrieve`    | Query a knowledge base (deprecated, use `search`) |
-| `config show` | Display current configuration                     |
-| `config set`  | Set a configuration value                         |
-| `update`      | Self-update to the latest version                 |
+### Knowledge Base Management
+
+| Command     | Description                                               |
+| :---------- | :-------------------------------------------------------- |
+| `kb list`   | List knowledge bases in the current workspace             |
+| `kb info`   | Show details of a knowledge base                          |
+| `kb create` | Create a new knowledge base                               |
+| `kb update` | Update knowledge base settings                            |
+| `kb delete` | Delete a knowledge base                                   |
+| `kb stats`  | Show storage and document statistics for a knowledge base |
+
+### Document Management
+
+| Command          | Description                                     |
+| :--------------- | :---------------------------------------------- |
+| `doc list`       | List documents in a knowledge base              |
+| `doc upload`     | Upload a document to a knowledge base           |
+| `doc status`     | Show processing status of a document            |
+| `doc delete`     | Delete a document from a knowledge base         |
+| `doc tag`        | Add or update tags on a document                |
+| `doc import-oss` | Import documents from OSS into a knowledge base |
+
+### Retrieval Services
+
+| Command          | Description                            |
+| :--------------- | :------------------------------------- |
+| `service list`   | List retrieval services                |
+| `service get`    | Show details of a retrieval service    |
+| `service create` | Create a retrieval service             |
+| `service update` | Update retrieval service settings      |
+| `service deploy` | Deploy or rebind a retrieval service   |
+| `service delete` | Delete a retrieval service             |
+| `service copy`   | Copy a retrieval service configuration |
+
+### Chunk Management
+
+| Command        | Description                    |
+| :------------- | :----------------------------- |
+| `chunk add`    | Add a text chunk to a document |
+| `chunk list`   | List chunks in a document      |
+| `chunk update` | Update a text chunk            |
+| `chunk delete` | Delete a chunk from a document |
+
+### Data Center Files
+
+| Command       | Description                        |
+| :------------ | :--------------------------------- |
+| `file list`   | List files in the data center      |
+| `file get`    | Show details of a data center file |
+| `file delete` | Delete a file from the data center |
+
+### Collections & Categories
+
+| Command             | Description                             |
+| :------------------ | :-------------------------------------- |
+| `collection create` | Create a collection in a knowledge base |
+| `collection get`    | Show details of a collection            |
+| `category list`     | List categories in a knowledge base     |
+| `category add`      | Add a category to a knowledge base      |
+| `category delete`   | Delete a category from a knowledge base |
+
+### Retrieval & Chat
+
+| Command    | Description                                       |
+| :--------- | :------------------------------------------------ |
+| `search`   | Semantic search across knowledge bases (RAG)      |
+| `chat`     | Knowledge-base Q&A with streaming (RAG)           |
+| `retrieve` | Query a knowledge base (deprecated, use `search`) |
+
+### Utility
+
+| Command       | Description                       |
+| :------------ | :-------------------------------- |
+| `config show` | Display current configuration     |
+| `config set`  | Set a configuration value         |
+| `update`      | Self-update to the latest version |
+
+> For full parameter details, output formats, and usage examples, see the [CLI Guide](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md).
 
 ## Authentication
 
@@ -83,13 +182,27 @@ kscli update
 
 Config file location: `~/.bailian/config.json`
 
+### Global Flags
+
+All commands support these common flags:
+
+| Flag        | Description                                          |
+| :---------- | :--------------------------------------------------- |
+| `--output`  | Output format: `text` (default) or `json`            |
+| `--quiet`   | Print only the result value, no headers or hints     |
+| `--dry-run` | Preview the request without sending it to the server |
+| `--timeout` | Request timeout in seconds (default: 60)             |
+| `--verbose` | Show verbose output including HTTP details           |
+| `--config`  | Path to a custom config file                         |
+
 ## Links
 
-| Resource                 | URL                                                  |
-| :----------------------- | :--------------------------------------------------- |
-| Knowledge Studio Console | https://rag.console.aliyun.com/                      |
-| DashScope API Docs       | https://help.aliyun.com/zh/model-studio/             |
-| Get API Key              | https://bailian.console.aliyun.com/?tab=app#/api-key |
+| Resource                 | URL                                                                                                       |
+| :----------------------- | :-------------------------------------------------------------------------------------------------------- |
+| Knowledge Studio Console | https://rag.console.aliyun.com/                                                                           |
+| DashScope API Docs       | https://help.aliyun.com/zh/model-studio/                                                                  |
+| Get API Key              | https://bailian.console.aliyun.com/?tab=app#/api-key                                                      |
+| Full CLI Guide           | [docs/knowledge-cli-guide.md](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md) |
 
 ## Contributing
 
diff --git a/packages/kscli/README.zh.md b/packages/kscli/README.zh.md
index 6a1b391f..5e0a44cb 100644
--- a/packages/kscli/README.zh.md
+++ b/packages/kscli/README.zh.md
@@ -9,13 +9,24 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](https://www.typescriptlang.org)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
-[Knowledge Studio 控制台](https://rag.console.aliyun.com/) · [English](README.md) · [API 文档](https://help.aliyun.com/zh/model-studio/)
+[Knowledge Studio 控制台](https://rag.console.aliyun.com/) · [English](README.md) · [API 文档](https://help.aliyun.com/zh/model-studio/) · [完整 CLI 指南](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md)
 
 </div>
 
 ## 这是什么？
 
-`kscli` 是阿里云 Model Studio (DashScope) 平台的**知识库检索**专用命令行工具，专为 RAG（检索增强生成）场景打造。
+`kscli` 是阿里云 Model Studio (DashScope) 平台的**知识库检索**专用命令行工具，专为 RAG（检索增强生成）场景打造。覆盖知识库全生命周期管理 — 从创建知识库、文档导入到语义检索与对话问答。
+
+## 功能特性
+
+- **知识库管理** — 创建、更新、删除、查看知识库；查看存储与文档统计信息
+- **文档管理** — 上传文件、从 OSS 导入、跟踪处理状态、打标签、删除文档
+- **检索服务** — 创建、配置、部署、复制和管理检索服务，将知识库绑定到指定模型
+- **Chunk 管理** — 在文档内新增、列出、更新、删除文本分片，实现细粒度内容控制
+- **数据中心** — 管理工作区数据中心的独立文件，在挂载到知识库前进行预处理
+- **集合与分类** — 通过集合组织知识库，通过分类对文档进行标记，实现范围检索
+- **RAG 检索与对话** — 跨知识库语义检索，流式问答返回基于知识的回答
+- **Agent 友好** — 支持 JSON 结构化输出（`--output json`）、预览模式（`--dry-run`）和静默模式（`--quiet`），便于脚本集成
 
 ## 安装
 
@@ -28,13 +39,31 @@ npm install -g knowledge-studio-cli
 ## 快速开始
 
 ```bash
-# 检索知识库
+# 1. 创建知识库
+kscli kb create \
+  --name "my-kb" \
+  --embedding-model text-embedding-v3 \
+  --workspace-id <your-workspace-id>
+
+# 2. 上传文档
+kscli doc upload \
+  --kb-id <kb-id> \
+  --file ./product-docs.pdf \
+  --workspace-id <your-workspace-id>
+
+# 3. 查看处理状态
+kscli doc status \
+  --kb-id <kb-id> \
+  --doc-id <doc-id> \
+  --workspace-id <your-workspace-id>
+
+# 4. 语义检索
 kscli search \
   --query "什么是 Model Studio？" \
   --agent-id <your-agent-id> \
   --workspace-id <your-workspace-id>
 
-# 知识库问答
+# 5. 知识库问答（流式输出）
 kscli chat \
   --message "什么是RAG？" \
   --agent-id <your-agent-id> \
@@ -43,14 +72,84 @@ kscli chat \
 
 ## 命令列表
 
-| 命令          | 说明                                  |
-| :------------ | :------------------------------------ |
-| `search`      | 知识库语义检索（RAG）                 |
-| `chat`        | 知识库问答（流式输出）                |
-| `retrieve`    | 查询知识库（已弃用，请使用 `search`） |
-| `config show` | 显示当前配置                          |
-| `config set`  | 设置配置项                            |
-| `update`      | 自更新到最新版本                      |
+### 知识库管理
+
+| 命令        | 说明                         |
+| :---------- | :--------------------------- |
+| `kb list`   | 列出当前工作区的知识库       |
+| `kb info`   | 查看知识库详情               |
+| `kb create` | 创建新知识库                 |
+| `kb update` | 更新知识库配置               |
+| `kb delete` | 删除知识库                   |
+| `kb stats`  | 查看知识库存储与文档统计信息 |
+
+### 文档管理
+
+| 命令             | 说明                    |
+| :--------------- | :---------------------- |
+| `doc list`       | 列出知识库中的文档      |
+| `doc upload`     | 上传文档到知识库        |
+| `doc status`     | 查看文档处理状态        |
+| `doc delete`     | 从知识库中删除文档      |
+| `doc tag`        | 添加或更新文档标签      |
+| `doc import-oss` | 从 OSS 导入文档到知识库 |
+
+### 检索服务
+
+| 命令             | 说明                   |
+| :--------------- | :--------------------- |
+| `service list`   | 列出检索服务           |
+| `service get`    | 查看检索服务详情       |
+| `service create` | 创建检索服务           |
+| `service update` | 更新检索服务配置       |
+| `service deploy` | 部署或重新绑定检索服务 |
+| `service delete` | 删除检索服务           |
+| `service copy`   | 复制检索服务配置       |
+
+### Chunk 管理
+
+| 命令           | 说明               |
+| :------------- | :----------------- |
+| `chunk add`    | 向文档添加文本分片 |
+| `chunk list`   | 列出文档中的分片   |
+| `chunk update` | 更新文本分片       |
+| `chunk delete` | 删除文档中的分片   |
+
+### 数据中心文件
+
+| 命令          | 说明                 |
+| :------------ | :------------------- |
+| `file list`   | 列出数据中心文件     |
+| `file get`    | 查看数据中心文件详情 |
+| `file delete` | 删除数据中心文件     |
+
+### 集合与分类
+
+| 命令                | 说明               |
+| :------------------ | :----------------- |
+| `collection create` | 在知识库中创建集合 |
+| `collection get`    | 查看集合详情       |
+| `category list`     | 列出知识库中的分类 |
+| `category add`      | 向知识库添加分类   |
+| `category delete`   | 删除知识库中的分类 |
+
+### 检索与对话
+
+| 命令       | 说明                                  |
+| :--------- | :------------------------------------ |
+| `search`   | 跨知识库语义检索（RAG）               |
+| `chat`     | 知识库问答（流式输出）                |
+| `retrieve` | 查询知识库（已弃用，请使用 `search`） |
+
+### 工具命令
+
+| 命令          | 说明             |
+| :------------ | :--------------- |
+| `config show` | 显示当前配置     |
+| `config set`  | 设置配置项       |
+| `update`      | 自更新到最新版本 |
+
+> 完整参数说明、输出格式与使用示例请参阅 [CLI 指南](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md)。
 
 ## 认证方式
 
@@ -60,7 +159,7 @@ kscli chat \
 # 方式一：环境变量
 export DASHSCOPE_API_KEY=sk-xxxxx
 
-# 方式二：登录命令（持久化到 ~/.bailian/config.json）
+# 方式二：持久化到配置文件（~/.bailian/config.json）
 kscli config set --key api_key --value sk-xxxxx
 
 # 方式三：命令行参数
@@ -77,19 +176,38 @@ kscli config show
 kscli config set --key base_url --value https://dashscope-us.aliyuncs.com
 kscli config set --key timeout --value 600
 
+# 设置默认工作区（可免去每次命令传 --workspace-id）
+kscli config set --key workspace_id --value <your-workspace-id>
+
 # 自更新
 kscli update
 ```
 
 配置文件位置：`~/.bailian/config.json`
 
+> `--workspace-id` 的解析优先级：命令行参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > 配置文件中的 `workspace_id`。
+
+### 全局参数
+
+所有命令均支持以下通用参数：
+
+| 参数        | 说明                                     |
+| :---------- | :--------------------------------------- |
+| `--output`  | 输出格式：`text`（默认）或 `json`        |
+| `--quiet`   | 静默模式，仅输出结果值，不显示表头和提示 |
+| `--dry-run` | 预览请求结构，不实际发送到服务端         |
+| `--timeout` | 请求超时时间，单位秒（默认 60）          |
+| `--verbose` | 显示详细输出，包括 HTTP 请求详情         |
+| `--config`  | 指定自定义配置文件路径                   |
+
 ## 相关链接
 
-| 资源                    | 地址                                                 |
-| :---------------------- | :--------------------------------------------------- |
-| Knowledge Studio 控制台 | https://rag.console.aliyun.com/                      |
-| DashScope API 文档      | https://help.aliyun.com/zh/model-studio/             |
-| 获取 API Key            | https://bailian.console.aliyun.com/?tab=app#/api-key |
+| 资源                    | 地址                                                                                                      |
+| :---------------------- | :-------------------------------------------------------------------------------------------------------- |
+| Knowledge Studio 控制台 | https://rag.console.aliyun.com/                                                                           |
+| DashScope API 文档      | https://help.aliyun.com/zh/model-studio/                                                                  |
+| 获取 API Key            | https://bailian.console.aliyun.com/?tab=app#/api-key                                                      |
+| 完整 CLI 指南           | [docs/knowledge-cli-guide.md](https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md) |
 
 ## 参与贡献
 
diff --git a/packages/kscli/package.json b/packages/kscli/package.json
index f90a134e..a63de0cd 100644
--- a/packages/kscli/package.json
+++ b/packages/kscli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "knowledge-studio-cli",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Lightweight RAG CLI for Aliyun Model Studio — focused on knowledge-base retrieval.",
   "keywords": [
     "alibaba-cloud",
diff --git a/packages/kscli/src/commands.ts b/packages/kscli/src/commands.ts
index ad49dff4..aa67f9cb 100644
--- a/packages/kscli/src/commands.ts
+++ b/packages/kscli/src/commands.ts
@@ -6,6 +6,37 @@ import {
   knowledgeRetrieve,
   knowledgeSearch,
   knowledgeChat,
+  knowledgeKbList,
+  knowledgeKbInfo,
+  knowledgeDocList,
+  knowledgeDocStatus,
+  knowledgeDocUpload,
+  knowledgeKbCreate,
+  knowledgeKbUpdate,
+  knowledgeKbDelete,
+  knowledgeDocDelete,
+  knowledgeDocTag,
+  knowledgeServiceList,
+  knowledgeServiceGet,
+  knowledgeServiceCreate,
+  knowledgeServiceUpdate,
+  knowledgeServiceDeploy,
+  knowledgeServiceDelete,
+  knowledgeServiceCopy,
+  knowledgeChunkAdd,
+  knowledgeChunkList,
+  knowledgeChunkUpdate,
+  knowledgeChunkDelete,
+  knowledgeKbStats,
+  knowledgeCategoryList,
+  knowledgeCategoryAdd,
+  knowledgeCategoryDelete,
+  knowledgeFileList,
+  knowledgeFileGet,
+  knowledgeFileDelete,
+  knowledgeCollectionCreate,
+  knowledgeCollectionGet,
+  knowledgeDocImportOss,
 } from "bailian-cli-commands";
 
 // kscli (Knowledge Studio CLI): lightweight RAG product. Ships config/update
@@ -20,4 +51,35 @@ export const commands: Record<string, AnyCommand> = {
   retrieve: knowledgeRetrieve,
   search: knowledgeSearch,
   chat: knowledgeChat,
+  "kb list": knowledgeKbList,
+  "kb info": knowledgeKbInfo,
+  "kb create": knowledgeKbCreate,
+  "kb update": knowledgeKbUpdate,
+  "kb delete": knowledgeKbDelete,
+  "doc list": knowledgeDocList,
+  "doc status": knowledgeDocStatus,
+  "doc upload": knowledgeDocUpload,
+  "doc delete": knowledgeDocDelete,
+  "doc tag": knowledgeDocTag,
+  "service list": knowledgeServiceList,
+  "service get": knowledgeServiceGet,
+  "service create": knowledgeServiceCreate,
+  "service update": knowledgeServiceUpdate,
+  "service deploy": knowledgeServiceDeploy,
+  "service delete": knowledgeServiceDelete,
+  "service copy": knowledgeServiceCopy,
+  "chunk add": knowledgeChunkAdd,
+  "chunk list": knowledgeChunkList,
+  "chunk update": knowledgeChunkUpdate,
+  "chunk delete": knowledgeChunkDelete,
+  "kb stats": knowledgeKbStats,
+  "category list": knowledgeCategoryList,
+  "category add": knowledgeCategoryAdd,
+  "category delete": knowledgeCategoryDelete,
+  "file list": knowledgeFileList,
+  "file get": knowledgeFileGet,
+  "file delete": knowledgeFileDelete,
+  "collection create": knowledgeCollectionCreate,
+  "collection get": knowledgeCollectionGet,
+  "doc import-oss": knowledgeDocImportOss,
 };
diff --git a/packages/runtime/package.json b/packages/runtime/package.json
index d540ec66..66fd7fdb 100644
--- a/packages/runtime/package.json
+++ b/packages/runtime/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bailian-cli-runtime",
-  "version": "1.15.1",
+  "version": "1.16.0",
   "description": "Runtime framework for bailian-cli (createCli, registry, args, output, pipeline). See https://www.npmjs.com/package/bailian-cli for usage.",
   "homepage": "https://bailian.console.aliyun.com/cli",
   "bugs": {
diff --git a/packages/runtime/src/confirm.ts b/packages/runtime/src/confirm.ts
new file mode 100644
index 00000000..43cf6c62
--- /dev/null
+++ b/packages/runtime/src/confirm.ts
@@ -0,0 +1,36 @@
+// Confirmation guard for dangerous operations — used by irreversible or
+// production-affecting commands (kb/doc/chunk/category/file delete, service
+// delete/deploy, ...).
+import { createInterface } from "node:readline/promises";
+import { BailianError, ExitCode } from "bailian-cli-core";
+
+/**
+ * - `yes` (the command's own --yes switch) → pass through
+ * - TTY: print the summary and wait for y/yes (case-insensitive); any other
+ *   input cancels with exit SUCCESS (cancellation is not an error)
+ * - non-TTY without --yes: throw USAGE
+ */
+export async function confirmDangerousAction(summary: string, yes: boolean): Promise<void> {
+  if (yes) return;
+  if (!process.stdin.isTTY) {
+    throw new BailianError(
+      "Confirmation required for this destructive action.",
+      ExitCode.USAGE,
+      "Re-run with --yes to confirm in non-interactive mode",
+    );
+  }
+  process.stderr.write(`${summary}\n`);
+  const readline = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await readline.question("Proceed? [y/N] ")).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      process.stderr.write("Cancelled.\n");
+      // Intentional: a user-initiated cancellation is not an error, and we want
+      // to exit here rather than unwind through the middleware stack (which
+      // would still print a success report for an action that did not happen).
+      process.exit(ExitCode.SUCCESS);
+    }
+  } finally {
+    readline.close();
+  }
+}
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index ce41f46c..215ec102 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -63,6 +63,7 @@ export {
 
 // Utility facilities consumed by commands
 export { poll } from "./utils/polling.ts";
+export { confirmDangerousAction } from "./confirm.ts";
 export { downloadFile, formatBytes } from "./utils/download.ts";
 export { runConcurrent, getConcurrency, downloadParallel } from "./utils/concurrent.ts";
 export { resolveImageSize } from "./utils/image-size.ts";
diff --git a/packages/runtime/tests/confirm.test.ts b/packages/runtime/tests/confirm.test.ts
new file mode 100644
index 00000000..e9fdba63
--- /dev/null
+++ b/packages/runtime/tests/confirm.test.ts
@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, test } from "vite-plus/test";
+import { ExitCode } from "bailian-cli-core";
+import { confirmDangerousAction } from "../src/confirm.ts";
+
+const originalIsTTY = process.stdin.isTTY;
+afterEach(() => {
+  process.stdin.isTTY = originalIsTTY;
+});
+
+describe("confirmDangerousAction", () => {
+  test("--yes 时直接通过,不触碰 stdin", async () => {
+    await expect(confirmDangerousAction("Delete kb idx-1", true)).resolves.toBeUndefined();
+  });
+
+  test("非 TTY 且无 --yes 时抛 USAGE 并引导 --yes", async () => {
+    process.stdin.isTTY = false;
+    try {
+      await confirmDangerousAction("Delete kb idx-1", false);
+      expect.unreachable("should throw");
+    } catch (error) {
+      expect((error as { exitCode: number }).exitCode).toBe(ExitCode.USAGE);
+      expect((error as { hint?: string }).hint).toMatch(/--yes/);
+    }
+  });
+});
diff --git a/skills/bailian-cli/SKILL.md b/skills/bailian-cli/SKILL.md
index 5bec91ce..6632b281 100644
--- a/skills/bailian-cli/SKILL.md
+++ b/skills/bailian-cli/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: bailian-cli
 metadata:
-  version: "1.15.1"
+  version: "1.16.0"
   requires:
     bins: ["bl"]
 description: >-
diff --git a/skills/bailian-cli/reference/index.md b/skills/bailian-cli/reference/index.md
index 39916369..9b79c3f5 100644
--- a/skills/bailian-cli/reference/index.md
+++ b/skills/bailian-cli/reference/index.md
@@ -9,96 +9,127 @@ Use this index for the skill-scoped quick index and global flags.
 
 ## Quick index
 
-| Command                         | Authentication | Description                                                                                    | Detail                         |
-| ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------- | ------------------------------ |
-| `bl advisor recommend`          | API Key        | Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking) | [advisor.md](advisor.md)       |
-| `bl app call`                   | API Key        | Call a Bailian application (agent or workflow)                                                 | [app.md](app.md)               |
-| `bl app list`                   | Console        | List Bailian applications                                                                      | [app.md](app.md)               |
-| `bl auth generate-access-token` | No Auth        | Generate a CLI access token using OpenAPI AK/SK                                                | [auth.md](auth.md)             |
-| `bl auth login`                 | No Auth        | Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist)   | [auth.md](auth.md)             |
-| `bl auth logout`                | No Auth        | Clear stored credentials; full logout also clears the model Base URL                           | [auth.md](auth.md)             |
-| `bl auth status`                | No Auth        | Show current authentication state                                                              | [auth.md](auth.md)             |
-| `bl config agent`               | No Auth        | Configure a coding agent to use DashScope API                                                  | [config.md](config.md)         |
-| `bl config list`                | No Auth        | List config profiles and show the active profile                                               | [config.md](config.md)         |
-| `bl config set`                 | No Auth        | Set a config value                                                                             | [config.md](config.md)         |
-| `bl config show`                | No Auth        | Display current configuration                                                                  | [config.md](config.md)         |
-| `bl config ui`                  | No Auth        | Open a local web UI to manage config profiles                                                  | [config.md](config.md)         |
-| `bl config use`                 | No Auth        | Set the active config profile                                                                  | [config.md](config.md)         |
-| `bl console call`               | Console        | Call a Bailian console API via the CLI gateway                                                 | [console.md](console.md)       |
-| `bl file upload`                | API Key        | Upload a local file to DashScope temporary storage (48h)                                       | [file.md](file.md)             |
-| `bl knowledge chat`             | API Key        | Chat with a Bailian knowledge base (RAG Q&A with streaming)                                    | [knowledge.md](knowledge.md)   |
-| `bl knowledge retrieve`         | API Key        | Retrieve from a Bailian knowledge base (deprecated, use `search` instead)                      | [knowledge.md](knowledge.md)   |
-| `bl knowledge search`           | API Key        | Search a Bailian knowledge base (RAG semantic retrieval)                                       | [knowledge.md](knowledge.md)   |
-| `bl mcp call`                   | API Key        | Call a tool on an MCP server (tools/call)                                                      | [mcp.md](mcp.md)               |
-| `bl mcp list`                   | Console        | List MCP servers activated under your Bailian account                                          | [mcp.md](mcp.md)               |
-| `bl mcp tools`                  | API Key        | List tools exposed by an MCP server (tools/list)                                               | [mcp.md](mcp.md)               |
-| `bl memory add`                 | API Key        | Add memory from messages or custom content                                                     | [memory.md](memory.md)         |
-| `bl memory delete`              | API Key        | Delete a memory node                                                                           | [memory.md](memory.md)         |
-| `bl memory list`                | API Key        | List memory nodes for a user                                                                   | [memory.md](memory.md)         |
-| `bl memory profile create`      | API Key        | Create a user profile schema for memory profiling                                              | [memory.md](memory.md)         |
-| `bl memory profile get`         | API Key        | Get user profile by schema ID and user ID                                                      | [memory.md](memory.md)         |
-| `bl memory search`              | API Key        | Search memory nodes by query or messages                                                       | [memory.md](memory.md)         |
-| `bl memory update`              | API Key        | Update a memory node content                                                                   | [memory.md](memory.md)         |
-| `bl model list`                 | No Auth        | Browse model families or show detailed model info in the Bailian model marketplace             | [model.md](model.md)           |
-| `bl permission grant`           | API Key        | Grant model permissions (inference / finetune / deploy)                                        | [permission.md](permission.md) |
-| `bl permission list`            | API Key        | List model permissions (inference / fine-tune / deploy) in the workspace                       | [permission.md](permission.md) |
-| `bl permission revoke`          | API Key        | Revoke model permissions (inference / finetune / deploy)                                       | [permission.md](permission.md) |
-| `bl pipeline run`               | No Auth        | Run a pipeline workflow definition                                                             | [pipeline.md](pipeline.md)     |
-| `bl pipeline validate`          | No Auth        | Validate a pipeline definition without executing                                               | [pipeline.md](pipeline.md)     |
-| `bl plugin install`             | No Auth        | Install or upgrade an allowlisted Command Pack                                                 | [plugin.md](plugin.md)         |
-| `bl plugin link`                | No Auth        | Link an allowlisted local Command Pack for development                                         | [plugin.md](plugin.md)         |
-| `bl plugin list`                | No Auth        | List installed Command Packs and their load status                                             | [plugin.md](plugin.md)         |
-| `bl plugin remove`              | No Auth        | Remove an installed Command Pack                                                               | [plugin.md](plugin.md)         |
-| `bl quota check`                | Console        | Check current usage against rate limits                                                        | [quota.md](quota.md)           |
-| `bl quota history`              | Console        | View quota change history                                                                      | [quota.md](quota.md)           |
-| `bl quota list`                 | API Key        | View model rate limits (QPM/TPM, account and workspace level)                                  | [quota.md](quota.md)           |
-| `bl quota update`               | API Key        | Update model rate limits (QPM/TPM), or clear them with --delete                                | [quota.md](quota.md)           |
-| `bl search web`                 | API Key        | Search the web using DashScope MCP WebSearch service                                           | [search.md](search.md)         |
-| `bl skill add`                  | No Auth        | Install skills from the Bailian skill registry into local agents                               | [skill.md](skill.md)           |
-| `bl skill init`                 | No Auth        | Install all bailian-\* skills (one-shot bootstrap for new environments)                        | [skill.md](skill.md)           |
-| `bl skill list`                 | No Auth        | List registry skills and diff against local installs                                           | [skill.md](skill.md)           |
-| `bl skill remove`               | No Auth        | Remove locally installed skills (registry is untouched)                                        | [skill.md](skill.md)           |
-| `bl skill update`               | No Auth        | Update installed skills to the latest registry versions                                        | [skill.md](skill.md)           |
-| `bl text chat`                  | API Key        | Send a text model request (OpenAI compatible, DashScope)                                       | [text.md](text.md)             |
-| `bl token-plan add-member`      | AK/SK          | Add a member to a Token Plan organization                                                      | [token-plan.md](token-plan.md) |
-| `bl token-plan assign-seats`    | AK/SK          | Batch assign Token Plan seats to members                                                       | [token-plan.md](token-plan.md) |
-| `bl token-plan create-key`      | AK/SK          | Create a Token Plan API key for a seat                                                         | [token-plan.md](token-plan.md) |
-| `bl token-plan list-seats`      | AK/SK          | List Token Plan subscription seat details                                                      | [token-plan.md](token-plan.md) |
-| `bl update`                     | No Auth        | Update the CLI to the latest or a specified version                                            | [update.md](update.md)         |
-| `bl usage coding-plan`          | Console        | Show Coding Plan quota usage                                                                   | [usage.md](usage.md)           |
-| `bl usage free`                 | Console        | Query free-tier quota for models (all models if --model is omitted)                            | [usage.md](usage.md)           |
-| `bl usage freetier`             | Console        | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable     | [usage.md](usage.md)           |
-| `bl usage stats`                | Console        | Query model usage statistics                                                                   | [usage.md](usage.md)           |
-| `bl usage summary`              | Console        | Show a unified usage summary: free-tier quota and recent usage overview                        | [usage.md](usage.md)           |
-| `bl usage token-plan`           | Console        | Show Token Plan quota usage                                                                    | [usage.md](usage.md)           |
-| `bl workspace init`             | No Auth        | Initialize Bailian workspace and activate postpaid services                                    | [workspace.md](workspace.md)   |
-| `bl workspace list`             | Console        | List all workspaces                                                                            | [workspace.md](workspace.md)   |
+| Command                          | Authentication | Description                                                                                      | Detail                         |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
+| `bl advisor recommend`           | API Key        | Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking)   | [advisor.md](advisor.md)       |
+| `bl app call`                    | API Key        | Call a Bailian application (agent or workflow)                                                   | [app.md](app.md)               |
+| `bl app list`                    | Console        | List Bailian applications                                                                        | [app.md](app.md)               |
+| `bl auth generate-access-token`  | No Auth        | Generate a CLI access token using OpenAPI AK/SK                                                  | [auth.md](auth.md)             |
+| `bl auth login`                  | No Auth        | Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist)     | [auth.md](auth.md)             |
+| `bl auth logout`                 | No Auth        | Clear stored credentials; full logout also clears the model Base URL                             | [auth.md](auth.md)             |
+| `bl auth status`                 | No Auth        | Show current authentication state                                                                | [auth.md](auth.md)             |
+| `bl config agent`                | No Auth        | Configure a coding agent to use DashScope API                                                    | [config.md](config.md)         |
+| `bl config list`                 | No Auth        | List config profiles and show the active profile                                                 | [config.md](config.md)         |
+| `bl config set`                  | No Auth        | Set a config value                                                                               | [config.md](config.md)         |
+| `bl config show`                 | No Auth        | Display current configuration                                                                    | [config.md](config.md)         |
+| `bl config ui`                   | No Auth        | Open a local web UI to manage config profiles                                                    | [config.md](config.md)         |
+| `bl config use`                  | No Auth        | Set the active config profile                                                                    | [config.md](config.md)         |
+| `bl console call`                | Console        | Call a Bailian console API via the CLI gateway                                                   | [console.md](console.md)       |
+| `bl file upload`                 | API Key        | Upload a local file to DashScope temporary storage (48h)                                         | [file.md](file.md)             |
+| `bl knowledge category add`      | API Key        | Create a data-center category                                                                    | [knowledge.md](knowledge.md)   |
+| `bl knowledge category delete`   | API Key        | Delete a data-center category                                                                    | [knowledge.md](knowledge.md)   |
+| `bl knowledge category list`     | API Key        | List data-center categories                                                                      | [knowledge.md](knowledge.md)   |
+| `bl knowledge chat`              | API Key        | Chat with a Bailian knowledge base (RAG Q&A with streaming)                                      | [knowledge.md](knowledge.md)   |
+| `bl knowledge chunk add`         | API Key        | Add a chunk directly to a knowledge base                                                         | [knowledge.md](knowledge.md)   |
+| `bl knowledge chunk delete`      | API Key        | Delete chunks from a knowledge base (irreversible)                                               | [knowledge.md](knowledge.md)   |
+| `bl knowledge chunk list`        | API Key        | List chunks in a knowledge base with content and status                                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge chunk update`      | API Key        | Update chunk content or toggle its retrieval visibility                                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge collection create` | API Key        | Create a FILE data collection                                                                    | [knowledge.md](knowledge.md)   |
+| `bl knowledge collection get`    | API Key        | Show data collection details                                                                     | [knowledge.md](knowledge.md)   |
+| `bl knowledge create`            | API Key        | Create a knowledge base and import data-center files or categories                               | [knowledge.md](knowledge.md)   |
+| `bl knowledge delete`            | API Key        | Delete a knowledge base with all its documents and chunks                                        | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc delete`        | API Key        | Delete documents and their chunks from a knowledge base                                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc import-oss`    | API Key        | Batch import files from an authorized OSS bucket into the data center                            | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc list`          | API Key        | List documents in a knowledge base with parse/index status                                       | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc status`        | API Key        | Check knowledge base import job status                                                           | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc tag`           | API Key        | Batch update tags on data-center files                                                           | [knowledge.md](knowledge.md)   |
+| `bl knowledge doc upload`        | API Key        | Upload local files or directories to the data center and optionally import into a knowledge base | [knowledge.md](knowledge.md)   |
+| `bl knowledge file delete`       | API Key        | Permanently delete a file from the data center                                                   | [knowledge.md](knowledge.md)   |
+| `bl knowledge file get`          | API Key        | Show data-center file details (size, MD5, tags, timestamps)                                      | [knowledge.md](knowledge.md)   |
+| `bl knowledge file list`         | API Key        | List files in a data-center category                                                             | [knowledge.md](knowledge.md)   |
+| `bl knowledge info`              | API Key        | Show knowledge base configuration details                                                        | [knowledge.md](knowledge.md)   |
+| `bl knowledge list`              | API Key        | List knowledge bases in the workspace                                                            | [knowledge.md](knowledge.md)   |
+| `bl knowledge retrieve`          | API Key        | Retrieve from a Bailian knowledge base (deprecated, use `search` instead)                        | [knowledge.md](knowledge.md)   |
+| `bl knowledge search`            | API Key        | Search a Bailian knowledge base (RAG semantic retrieval)                                         | [knowledge.md](knowledge.md)   |
+| `bl knowledge service copy`      | API Key        | Copy a service into a new draft (name gets a copy\_ prefix)                                      | [knowledge.md](knowledge.md)   |
+| `bl knowledge service create`    | API Key        | Create a retrieval / Q&A service (initial status: draft, version: beta)                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge service delete`    | API Key        | Delete a retrieval / Q&A service (soft delete, idempotent)                                       | [knowledge.md](knowledge.md)   |
+| `bl knowledge service deploy`    | API Key        | Publish the beta draft of a service as a new version                                             | [knowledge.md](knowledge.md)   |
+| `bl knowledge service get`       | API Key        | Show service (agent) details including per-version configuration                                 | [knowledge.md](knowledge.md)   |
+| `bl knowledge service list`      | API Key        | List retrieval / Q&A services (agents) in the workspace                                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge service update`    | API Key        | Update service name, description or draft configuration                                          | [knowledge.md](knowledge.md)   |
+| `bl knowledge stats`             | API Key        | Show knowledge base storage and QPS monitoring data                                              | [knowledge.md](knowledge.md)   |
+| `bl knowledge update`            | API Key        | Update knowledge base name, description or rerank threshold                                      | [knowledge.md](knowledge.md)   |
+| `bl mcp call`                    | API Key        | Call a tool on an MCP server (tools/call)                                                        | [mcp.md](mcp.md)               |
+| `bl mcp list`                    | Console        | List MCP servers activated under your Bailian account                                            | [mcp.md](mcp.md)               |
+| `bl mcp tools`                   | API Key        | List tools exposed by an MCP server (tools/list)                                                 | [mcp.md](mcp.md)               |
+| `bl memory add`                  | API Key        | Add memory from messages or custom content                                                       | [memory.md](memory.md)         |
+| `bl memory delete`               | API Key        | Delete a memory node                                                                             | [memory.md](memory.md)         |
+| `bl memory list`                 | API Key        | List memory nodes for a user                                                                     | [memory.md](memory.md)         |
+| `bl memory profile create`       | API Key        | Create a user profile schema for memory profiling                                                | [memory.md](memory.md)         |
+| `bl memory profile get`          | API Key        | Get user profile by schema ID and user ID                                                        | [memory.md](memory.md)         |
+| `bl memory search`               | API Key        | Search memory nodes by query or messages                                                         | [memory.md](memory.md)         |
+| `bl memory update`               | API Key        | Update a memory node content                                                                     | [memory.md](memory.md)         |
+| `bl model list`                  | No Auth        | Browse model families or show detailed model info in the Bailian model marketplace               | [model.md](model.md)           |
+| `bl permission grant`            | API Key        | Grant model permissions (inference / finetune / deploy)                                          | [permission.md](permission.md) |
+| `bl permission list`             | API Key        | List model permissions (inference / fine-tune / deploy) in the workspace                         | [permission.md](permission.md) |
+| `bl permission revoke`           | API Key        | Revoke model permissions (inference / finetune / deploy)                                         | [permission.md](permission.md) |
+| `bl pipeline run`                | No Auth        | Run a pipeline workflow definition                                                               | [pipeline.md](pipeline.md)     |
+| `bl pipeline validate`           | No Auth        | Validate a pipeline definition without executing                                                 | [pipeline.md](pipeline.md)     |
+| `bl plugin install`              | No Auth        | Install or upgrade an allowlisted Command Pack                                                   | [plugin.md](plugin.md)         |
+| `bl plugin link`                 | No Auth        | Link an allowlisted local Command Pack for development                                           | [plugin.md](plugin.md)         |
+| `bl plugin list`                 | No Auth        | List installed Command Packs and their load status                                               | [plugin.md](plugin.md)         |
+| `bl plugin remove`               | No Auth        | Remove an installed Command Pack                                                                 | [plugin.md](plugin.md)         |
+| `bl quota check`                 | Console        | Check current usage against rate limits                                                          | [quota.md](quota.md)           |
+| `bl quota history`               | Console        | View quota change history                                                                        | [quota.md](quota.md)           |
+| `bl quota list`                  | API Key        | View model rate limits (QPM/TPM, account and workspace level)                                    | [quota.md](quota.md)           |
+| `bl quota update`                | API Key        | Update model rate limits (QPM/TPM), or clear them with --delete                                  | [quota.md](quota.md)           |
+| `bl search web`                  | API Key        | Search the web using DashScope MCP WebSearch service                                             | [search.md](search.md)         |
+| `bl skill add`                   | No Auth        | Install skills from the Bailian skill registry into local agents                                 | [skill.md](skill.md)           |
+| `bl skill init`                  | No Auth        | Install all bailian-\* skills (one-shot bootstrap for new environments)                          | [skill.md](skill.md)           |
+| `bl skill list`                  | No Auth        | List registry skills and diff against local installs                                             | [skill.md](skill.md)           |
+| `bl skill remove`                | No Auth        | Remove locally installed skills (registry is untouched)                                          | [skill.md](skill.md)           |
+| `bl skill update`                | No Auth        | Update installed skills to the latest registry versions                                          | [skill.md](skill.md)           |
+| `bl text chat`                   | API Key        | Send a text model request (OpenAI compatible, DashScope)                                         | [text.md](text.md)             |
+| `bl token-plan add-member`       | AK/SK          | Add a member to a Token Plan organization                                                        | [token-plan.md](token-plan.md) |
+| `bl token-plan assign-seats`     | AK/SK          | Batch assign Token Plan seats to members                                                         | [token-plan.md](token-plan.md) |
+| `bl token-plan create-key`       | AK/SK          | Create a Token Plan API key for a seat                                                           | [token-plan.md](token-plan.md) |
+| `bl token-plan list-seats`       | AK/SK          | List Token Plan subscription seat details                                                        | [token-plan.md](token-plan.md) |
+| `bl update`                      | No Auth        | Update the CLI to the latest or a specified version                                              | [update.md](update.md)         |
+| `bl usage coding-plan`           | Console        | Show Coding Plan quota usage                                                                     | [usage.md](usage.md)           |
+| `bl usage free`                  | Console        | Query free-tier quota for models (all models if --model is omitted)                              | [usage.md](usage.md)           |
+| `bl usage freetier`              | Console        | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable       | [usage.md](usage.md)           |
+| `bl usage stats`                 | Console        | Query model usage statistics                                                                     | [usage.md](usage.md)           |
+| `bl usage summary`               | Console        | Show a unified usage summary: free-tier quota and recent usage overview                          | [usage.md](usage.md)           |
+| `bl usage token-plan`            | Console        | Show Token Plan quota usage                                                                      | [usage.md](usage.md)           |
+| `bl workspace init`              | No Auth        | Initialize Bailian workspace and activate postpaid services                                      | [workspace.md](workspace.md)   |
+| `bl workspace list`              | Console        | List all workspaces                                                                              | [workspace.md](workspace.md)   |
 
 ## By group
 
-| Group        | Commands                                                                     | Reference                      |
-| ------------ | ---------------------------------------------------------------------------- | ------------------------------ |
-| `advisor`    | `recommend`                                                                  | [advisor.md](advisor.md)       |
-| `app`        | `call`, `list`                                                               | [app.md](app.md)               |
-| `auth`       | `generate-access-token`, `login`, `logout`, `status`                         | [auth.md](auth.md)             |
-| `config`     | `agent`, `list`, `set`, `show`, `ui`, `use`                                  | [config.md](config.md)         |
-| `console`    | `call`                                                                       | [console.md](console.md)       |
-| `file`       | `upload`                                                                     | [file.md](file.md)             |
-| `knowledge`  | `chat`, `retrieve`, `search`                                                 | [knowledge.md](knowledge.md)   |
-| `mcp`        | `call`, `list`, `tools`                                                      | [mcp.md](mcp.md)               |
-| `memory`     | `add`, `delete`, `list`, `profile create`, `profile get`, `search`, `update` | [memory.md](memory.md)         |
-| `model`      | `list`                                                                       | [model.md](model.md)           |
-| `permission` | `grant`, `list`, `revoke`                                                    | [permission.md](permission.md) |
-| `pipeline`   | `run`, `validate`                                                            | [pipeline.md](pipeline.md)     |
-| `plugin`     | `install`, `link`, `list`, `remove`                                          | [plugin.md](plugin.md)         |
-| `quota`      | `check`, `history`, `list`, `update`                                         | [quota.md](quota.md)           |
-| `search`     | `web`                                                                        | [search.md](search.md)         |
-| `skill`      | `add`, `init`, `list`, `remove`, `update`                                    | [skill.md](skill.md)           |
-| `text`       | `chat`                                                                       | [text.md](text.md)             |
-| `token-plan` | `add-member`, `assign-seats`, `create-key`, `list-seats`                     | [token-plan.md](token-plan.md) |
-| `update`     | `(root)`                                                                     | [update.md](update.md)         |
-| `usage`      | `coding-plan`, `free`, `freetier`, `stats`, `summary`, `token-plan`          | [usage.md](usage.md)           |
-| `workspace`  | `init`, `list`                                                               | [workspace.md](workspace.md)   |
+| Group        | Commands                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Reference                      |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `advisor`    | `recommend`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [advisor.md](advisor.md)       |
+| `app`        | `call`, `list`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [app.md](app.md)               |
+| `auth`       | `generate-access-token`, `login`, `logout`, `status`                                                                                                                                                                                                                                                                                                                                                                                                                                        | [auth.md](auth.md)             |
+| `config`     | `agent`, `list`, `set`, `show`, `ui`, `use`                                                                                                                                                                                                                                                                                                                                                                                                                                                 | [config.md](config.md)         |
+| `console`    | `call`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [console.md](console.md)       |
+| `file`       | `upload`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [file.md](file.md)             |
+| `knowledge`  | `category add`, `category delete`, `category list`, `chat`, `chunk add`, `chunk delete`, `chunk list`, `chunk update`, `collection create`, `collection get`, `create`, `delete`, `doc delete`, `doc import-oss`, `doc list`, `doc status`, `doc tag`, `doc upload`, `file delete`, `file get`, `file list`, `info`, `list`, `retrieve`, `search`, `service copy`, `service create`, `service delete`, `service deploy`, `service get`, `service list`, `service update`, `stats`, `update` | [knowledge.md](knowledge.md)   |
+| `mcp`        | `call`, `list`, `tools`                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [mcp.md](mcp.md)               |
+| `memory`     | `add`, `delete`, `list`, `profile create`, `profile get`, `search`, `update`                                                                                                                                                                                                                                                                                                                                                                                                                | [memory.md](memory.md)         |
+| `model`      | `list`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [model.md](model.md)           |
+| `permission` | `grant`, `list`, `revoke`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [permission.md](permission.md) |
+| `pipeline`   | `run`, `validate`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | [pipeline.md](pipeline.md)     |
+| `plugin`     | `install`, `link`, `list`, `remove`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [plugin.md](plugin.md)         |
+| `quota`      | `check`, `history`, `list`, `update`                                                                                                                                                                                                                                                                                                                                                                                                                                                        | [quota.md](quota.md)           |
+| `search`     | `web`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [search.md](search.md)         |
+| `skill`      | `add`, `init`, `list`, `remove`, `update`                                                                                                                                                                                                                                                                                                                                                                                                                                                   | [skill.md](skill.md)           |
+| `text`       | `chat`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [text.md](text.md)             |
+| `token-plan` | `add-member`, `assign-seats`, `create-key`, `list-seats`                                                                                                                                                                                                                                                                                                                                                                                                                                    | [token-plan.md](token-plan.md) |
+| `update`     | `(root)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | [update.md](update.md)         |
+| `usage`      | `coding-plan`, `free`, `freetier`, `stats`, `summary`, `token-plan`                                                                                                                                                                                                                                                                                                                                                                                                                         | [usage.md](usage.md)           |
+| `workspace`  | `init`, `list`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | [workspace.md](workspace.md)   |
 
 ## Global flags
 
diff --git a/skills/bailian-cli/reference/knowledge.md b/skills/bailian-cli/reference/knowledge.md
index 4efa949f..ee3626d5 100644
--- a/skills/bailian-cli/reference/knowledge.md
+++ b/skills/bailian-cli/reference/knowledge.md
@@ -7,14 +7,153 @@ Index: [index.md](index.md)
 
 ## Commands in this group
 
-| Command                 | Authentication | Description                                                               |
-| ----------------------- | -------------- | ------------------------------------------------------------------------- |
-| `bl knowledge chat`     | API Key        | Chat with a Bailian knowledge base (RAG Q&A with streaming)               |
-| `bl knowledge retrieve` | API Key        | Retrieve from a Bailian knowledge base (deprecated, use `search` instead) |
-| `bl knowledge search`   | API Key        | Search a Bailian knowledge base (RAG semantic retrieval)                  |
+| Command                          | Authentication | Description                                                                                      |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
+| `bl knowledge category add`      | API Key        | Create a data-center category                                                                    |
+| `bl knowledge category delete`   | API Key        | Delete a data-center category                                                                    |
+| `bl knowledge category list`     | API Key        | List data-center categories                                                                      |
+| `bl knowledge chat`              | API Key        | Chat with a Bailian knowledge base (RAG Q&A with streaming)                                      |
+| `bl knowledge chunk add`         | API Key        | Add a chunk directly to a knowledge base                                                         |
+| `bl knowledge chunk delete`      | API Key        | Delete chunks from a knowledge base (irreversible)                                               |
+| `bl knowledge chunk list`        | API Key        | List chunks in a knowledge base with content and status                                          |
+| `bl knowledge chunk update`      | API Key        | Update chunk content or toggle its retrieval visibility                                          |
+| `bl knowledge collection create` | API Key        | Create a FILE data collection                                                                    |
+| `bl knowledge collection get`    | API Key        | Show data collection details                                                                     |
+| `bl knowledge create`            | API Key        | Create a knowledge base and import data-center files or categories                               |
+| `bl knowledge delete`            | API Key        | Delete a knowledge base with all its documents and chunks                                        |
+| `bl knowledge doc delete`        | API Key        | Delete documents and their chunks from a knowledge base                                          |
+| `bl knowledge doc import-oss`    | API Key        | Batch import files from an authorized OSS bucket into the data center                            |
+| `bl knowledge doc list`          | API Key        | List documents in a knowledge base with parse/index status                                       |
+| `bl knowledge doc status`        | API Key        | Check knowledge base import job status                                                           |
+| `bl knowledge doc tag`           | API Key        | Batch update tags on data-center files                                                           |
+| `bl knowledge doc upload`        | API Key        | Upload local files or directories to the data center and optionally import into a knowledge base |
+| `bl knowledge file delete`       | API Key        | Permanently delete a file from the data center                                                   |
+| `bl knowledge file get`          | API Key        | Show data-center file details (size, MD5, tags, timestamps)                                      |
+| `bl knowledge file list`         | API Key        | List files in a data-center category                                                             |
+| `bl knowledge info`              | API Key        | Show knowledge base configuration details                                                        |
+| `bl knowledge list`              | API Key        | List knowledge bases in the workspace                                                            |
+| `bl knowledge retrieve`          | API Key        | Retrieve from a Bailian knowledge base (deprecated, use `search` instead)                        |
+| `bl knowledge search`            | API Key        | Search a Bailian knowledge base (RAG semantic retrieval)                                         |
+| `bl knowledge service copy`      | API Key        | Copy a service into a new draft (name gets a copy\_ prefix)                                      |
+| `bl knowledge service create`    | API Key        | Create a retrieval / Q&A service (initial status: draft, version: beta)                          |
+| `bl knowledge service delete`    | API Key        | Delete a retrieval / Q&A service (soft delete, idempotent)                                       |
+| `bl knowledge service deploy`    | API Key        | Publish the beta draft of a service as a new version                                             |
+| `bl knowledge service get`       | API Key        | Show service (agent) details including per-version configuration                                 |
+| `bl knowledge service list`      | API Key        | List retrieval / Q&A services (agents) in the workspace                                          |
+| `bl knowledge service update`    | API Key        | Update service name, description or draft configuration                                          |
+| `bl knowledge stats`             | API Key        | Show knowledge base storage and QPS monitoring data                                              |
+| `bl knowledge update`            | API Key        | Update knowledge base name, description or rerank threshold                                      |
 
 ## Command details
 
+### `bl knowledge category add`
+
+| Field              | Value                                             |
+| ------------------ | ------------------------------------------------- |
+| **Name**           | `knowledge category add`                          |
+| **Description**    | Create a data-center category                     |
+| **Authentication** | API Key                                           |
+| **Usage**          | `bl knowledge category add --name <text> [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                        |
+| ---------------------- | ------ | -------- | ------------------------------------------------------------------ |
+| `--name <text>`        | string | yes      | Category name (1-20 chars)                                         |
+| `--parent-id <id>`     | string | no       | Create as a sub-category of this category                          |
+| `--collection-id <id>` | string | no       | Create under this collection (defaults to the platform collection) |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)    |
+| `--api-key <key>`      | string | no       | API key                                                            |
+| `--base-url <url>`     | string | no       | API base URL                                                       |
+
+#### Notes
+
+- Use categories to organize data-center files by business domain.
+
+#### Examples
+
+```bash
+bl knowledge category add --name product-docs --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge category add --name sub --parent-id cate-xxx
+```
+
+### `bl knowledge category delete`
+
+| Field              | Value                                                     |
+| ------------------ | --------------------------------------------------------- |
+| **Name**           | `knowledge category delete`                               |
+| **Description**    | Delete a data-center category                             |
+| **Authentication** | API Key                                                   |
+| **Usage**          | `bl knowledge category delete --category-id <id> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--category-id <id>`  | string | yes      | Category ID to delete                                           |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.
+
+#### Examples
+
+```bash
+bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge category delete --category-id cate-xxx --yes
+```
+
+### `bl knowledge category list`
+
+| Field              | Value                                |
+| ------------------ | ------------------------------------ |
+| **Name**           | `knowledge category list`            |
+| **Description**    | List data-center categories          |
+| **Authentication** | API Key                              |
+| **Usage**          | `bl knowledge category list [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                           |
+| ---------------------- | ------ | -------- | --------------------------------------------------------------------- |
+| `--collection-id <id>` | string | no       | Filter by exact collection ID                                         |
+| `--parent-id <id>`     | string | no       | List sub-categories of this exact parent category                     |
+| `--name <text>`        | string | no       | Filter by category name (exact match, unlike the knowledge base list) |
+| `--next-token <token>` | string | no       | Cursor for the next page (from previous output)                       |
+| `--max-result <n>`     | number | no       | Items per page (default: 20)                                          |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)       |
+| `--api-key <key>`      | string | no       | API key                                                               |
+| `--base-url <url>`     | string | no       | API base URL                                                          |
+
+#### Notes
+
+- Categories marked [default] are where files land when no category is specified.
+- Pagination is cursor-based: reuse the printed next token to continue.
+
+#### Examples
+
+```bash
+bl knowledge category list --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge category list --name my-category
+```
+
+```bash
+bl knowledge category list --next-token <token>
+```
+
 ### `bl knowledge chat`
 
 | Field              | Value                                                        |
@@ -26,14 +165,15 @@ Index: [index.md](index.md)
 
 #### Flags
 
-| Flag                  | Type   | Required | Description                                                                                                                            |
-| --------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `--message <text>`    | array  | no       | Message text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format |
-| `--agent-id <id>`     | string | yes      | Q&A service ID (find in console knowledge Q&A page)                                                                                    |
-| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                                        |
-| `--image <url>`       | array  | no       | Image URL (repeatable). Attached to the last user message as multimodal content                                                        |
-| `--api-key <key>`     | string | no       | API key                                                                                                                                |
-| `--base-url <url>`    | string | no       | API base URL                                                                                                                           |
+| Flag                        | Type   | Required | Description                                                                                                                            |
+| --------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `--message <text>`          | array  | no       | Message text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format |
+| `--agent-id <id>`           | string | yes      | Q&A service ID (find in console knowledge Q&A page)                                                                                    |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                                        |
+| `--agent-version <version>` | string | no       | Service version to call: beta (draft for debugging) or a published number; default is the latest published version                     |
+| `--image <url>`             | array  | no       | Image URL (repeatable). Attached to the last user message as multimodal content                                                        |
+| `--api-key <key>`           | string | no       | API key                                                                                                                                |
+| `--base-url <url>`          | string | no       | API base URL                                                                                                                           |
 
 #### Notes
 
@@ -41,6 +181,7 @@ Index: [index.md](index.md)
 - Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
 - `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.
 - Multi-turn: use --message "user:..." and --message "assistant:..." to pass conversation history.
+- `--agent-version beta` calls the draft config for debugging before it is deployed.
 
 #### Examples
 
@@ -56,6 +197,694 @@ bl knowledge chat --message "user:What is RAG?" --message "assistant:RAG is..."
 bl knowledge chat --message "Describe these images" --image https://example.com/a.png --image https://example.com/b.png --agent-id aid-xxx --workspace-id ws-xxx
 ```
 
+### `bl knowledge chunk add`
+
+| Field              | Value                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| **Name**           | `knowledge chunk add`                                                                |
+| **Description**    | Add a chunk directly to a knowledge base                                             |
+| **Authentication** | API Key                                                                              |
+| **Usage**          | `bl knowledge chunk add --index-id <id> (--content <text> \| --field <k=v>) [flags]` |
+
+#### Flags
+
+| Flag                    | Type   | Required | Description                                                                                                                                               |
+| ----------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--index-id <id>`       | string | yes      | Knowledge base ID                                                                                                                                         |
+| `--doc-id <id>`         | string | no       | Owning document ID from the doc list command; required in practice for all knowledge base types                                                           |
+| `--content <text>`      | string | no       | Chunk body text, up to 6000 chars (document-type); alternative to --content-file                                                                          |
+| `--content-file <path>` | string | no       | Read chunk body from a UTF-8 plain text file (.md/.txt etc.)                                                                                              |
+| `--title <text>`        | string | no       | Chunk title, up to 50 chars (document-type)                                                                                                               |
+| `--image-url <url>`     | array  | no       | Chunk image URL (repeatable, up to 10; document-type)                                                                                                     |
+| `--field <key=value>`   | array  | no       | Arbitrary field entry (repeatable) for table/image knowledge bases where keys are Excel column headers; mutually exclusive with content/title/image flags |
+| `--workspace-id <id>`   | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                                                           |
+| `--api-key <key>`       | string | no       | API key                                                                                                                                                   |
+| `--base-url <url>`      | string | no       | API base URL                                                                                                                                              |
+
+#### Notes
+
+- Document / table / image knowledge bases are supported; audio-video ones are not.
+- --doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.
+- Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.
+- The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.
+- The response carries no chunk id; list chunks afterwards to find the new one.
+- For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.
+
+#### Examples
+
+```bash
+bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
+```
+
+### `bl knowledge chunk delete`
+
+| Field              | Value                                                               |
+| ------------------ | ------------------------------------------------------------------- |
+| **Name**           | `knowledge chunk delete`                                            |
+| **Description**    | Delete chunks from a knowledge base (irreversible)                  |
+| **Authentication** | API Key                                                             |
+| **Usage**          | `bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                           |
+| --------------------- | ------ | -------- | --------------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                                     |
+| `--chunk-id <id>`     | array  | yes      | Chunk ID to delete (repeatable; batches of 10 are sent automatically) |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                          |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)       |
+| `--api-key <key>`     | string | no       | API key                                                               |
+| `--base-url <url>`    | string | no       | API base URL                                                          |
+
+#### Notes
+
+- Accepts at most 10 chunk ids per call; larger sets are batched automatically.
+
+#### Examples
+
+```bash
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
+```
+
+### `bl knowledge chunk list`
+
+| Field              | Value                                                   |
+| ------------------ | ------------------------------------------------------- |
+| **Name**           | `knowledge chunk list`                                  |
+| **Description**    | List chunks in a knowledge base with content and status |
+| **Authentication** | API Key                                                 |
+| **Usage**          | `bl knowledge chunk list --index-id <id> [flags]`       |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                               |
+| `--doc-id <id>`       | string | no       | Only show chunks belonging to this document                     |
+| `--page-number <n>`   | number | no       | Page number (default: 1)                                        |
+| `--page-size <n>`     | number | no       | Page size per request                                           |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Use metadata.\_id as the chunk id and metadata.doc_id as the document id in chunk update/delete commands.
+- Page size defaults to 20 (server default), max 100.
+
+#### Examples
+
+```bash
+bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
+```
+
+### `bl knowledge chunk update`
+
+| Field              | Value                                                                             |
+| ------------------ | --------------------------------------------------------------------------------- |
+| **Name**           | `knowledge chunk update`                                                          |
+| **Description**    | Update chunk content or toggle its retrieval visibility                           |
+| **Authentication** | API Key                                                                           |
+| **Usage**          | `bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]` |
+
+#### Flags
+
+| Flag                    | Type   | Required | Description                                                               |
+| ----------------------- | ------ | -------- | ------------------------------------------------------------------------- |
+| `--index-id <id>`       | string | yes      | Knowledge base ID                                                         |
+| `--chunk-id <id>`       | string | yes      | Chunk ID (metadata.\_id from the chunk list output)                       |
+| `--doc-id <id>`         | string | yes      | Document ID owning the chunk (metadata.doc_id from the chunk list output) |
+| `--content <text>`      | string | no       | New chunk content, 10-6000 chars; alternative to --content-file           |
+| `--content-file <path>` | string | no       | Read new content from a UTF-8 plain text file (.md/.txt etc.)             |
+| `--title <text>`        | string | no       | Chunk title, 0-50 chars (empty string clears it; omit to keep unchanged)  |
+| `--exclude`             | switch | no       | Exclude this chunk from retrieval                                         |
+| `--include`             | switch | no       | Include this chunk in retrieval (default)                                 |
+| `--workspace-id <id>`   | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)           |
+| `--api-key <key>`       | string | no       | API key                                                                   |
+| `--base-url <url>`      | string | no       | API base URL                                                              |
+
+#### Notes
+
+- Content must be 10-6000 characters and within the knowledge base's max chunk size.
+- --content-file expects a UTF-8 plain text file; document formats (.docx/.pdf) are not parsed here.
+- Toggling --exclude/--include without new content re-submits the existing content automatically.
+
+#### Examples
+
+```bash
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text"
+```
+
+```bash
+bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
+```
+
+### `bl knowledge collection create`
+
+| Field              | Value                                                                       |
+| ------------------ | --------------------------------------------------------------------------- |
+| **Name**           | `knowledge collection create`                                               |
+| **Description**    | Create a FILE data collection                                               |
+| **Authentication** | API Key                                                                     |
+| **Usage**          | `bl knowledge collection create --name <text> --description <text> [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                     |
+| ---------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--name <text>`        | string | yes      | Collection name                                                 |
+| `--description <text>` | string | yes      | Collection description (required by the server)                 |
+| `--store-type <type>`  | string | no       | Storage: platform (managed) or custom (your own OSS bucket)     |
+| `--oss-region <id>`    | string | no       | OSS region id (required with --store-type custom)               |
+| `--oss-bucket <name>`  | string | no       | OSS bucket name (required with --store-type custom)             |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`      | string | no       | API key                                                         |
+| `--base-url <url>`     | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Store type defaults to platform (managed storage); custom uses your authorized OSS bucket.
+- Custom buckets must carry the bucket tag bailian-connector-access=ReadAndWrite (Bailian's tag-based access control); without it the server rejects creation with a misleading 'setBucketCORS failed' error.
+- There is no collection delete API — create collections deliberately.
+
+#### Examples
+
+```bash
+bl knowledge collection create --name my-collection --description 'team docs' --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge collection create --name oss-coll --description 'own bucket' --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
+```
+
+### `bl knowledge collection get`
+
+| Field              | Value                                                                         |
+| ------------------ | ----------------------------------------------------------------------------- |
+| **Name**           | `knowledge collection get`                                                    |
+| **Description**    | Show data collection details                                                  |
+| **Authentication** | API Key                                                                       |
+| **Usage**          | `bl knowledge collection get (--collection-id <id> \| --name <text>) [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                     |
+| ---------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--collection-id <id>` | string | no       | Collection ID; alternative to --name                            |
+| `--name <text>`        | string | no       | Collection name; alternative to --collection-id                 |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`      | string | no       | API key                                                         |
+| `--base-url <url>`     | string | no       | API base URL                                                    |
+
+#### Examples
+
+```bash
+bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge collection get --name my-collection
+```
+
+### `bl knowledge create`
+
+| Field              | Value                                                                             |
+| ------------------ | --------------------------------------------------------------------------------- |
+| **Name**           | `knowledge create`                                                                |
+| **Description**    | Create a knowledge base and import data-center files or categories                |
+| **Authentication** | API Key                                                                           |
+| **Usage**          | `bl knowledge create --name <text> (--doc-id <id> \| --category-id <id>) [flags]` |
+
+#### Flags
+
+| Flag                        | Type   | Required | Description                                                                          |
+| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
+| `--name <text>`             | string | yes      | Knowledge base name (1-20 chars, unique in workspace)                                |
+| `--doc-id <id>`             | array  | no       | Data-center file id to import (repeatable); mutually exclusive with --category-id    |
+| `--category-id <id>`        | array  | no       | Import every file under this category (repeatable); mutually exclusive with --doc-id |
+| `--embedding-model <name>`  | string | no       | Embedding model name (default: text-embedding-v4)                                    |
+| `--chunk-size <n>`          | number | no       | Chunk size in characters (default: 600, recommended 300-800)                         |
+| `--wait`                    | switch | no       | Poll the initial import job to a terminal state                                      |
+| `--poll-interval <seconds>` | number | no       | Polling interval when waiting (default: 5)                                           |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                      |
+| `--api-key <key>`           | string | no       | API key                                                                              |
+| `--base-url <url>`          | string | no       | API base URL                                                                         |
+
+#### Notes
+
+- Structure/sink types are fixed to the default document knowledge base (unstructured, BUILT_IN storage).
+- Returns the knowledge base id (pipelineId) and the initial import job id (ingestionId).
+- Use the import job status command (or --wait) to track the initial import.
+
+#### Examples
+
+```bash
+bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge create --name demo --category-id cate-xxx --wait
+```
+
+### `bl knowledge delete`
+
+| Field              | Value                                                     |
+| ------------------ | --------------------------------------------------------- |
+| **Name**           | `knowledge delete`                                        |
+| **Description**    | Delete a knowledge base with all its documents and chunks |
+| **Authentication** | API Key                                                   |
+| **Usage**          | `bl knowledge delete --index-id <id> [flags]`             |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                               |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Irreversible — the knowledge base and all indexed content are permanently removed.
+- Files in the data center are not affected; only the knowledge base index is deleted.
+
+#### Examples
+
+```bash
+bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge delete --index-id idx-xxx --yes
+```
+
+### `bl knowledge doc delete`
+
+| Field              | Value                                                           |
+| ------------------ | --------------------------------------------------------------- |
+| **Name**           | `knowledge doc delete`                                          |
+| **Description**    | Delete documents and their chunks from a knowledge base         |
+| **Authentication** | API Key                                                         |
+| **Usage**          | `bl knowledge doc delete --index-id <id> --doc-id <id> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                               |
+| `--doc-id <id>`       | array  | yes      | Document ID to delete (repeatable)                              |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Removes documents from the knowledge base index only; the source files remain in the data center.
+- Use the doc_id from `knowledge doc list --quiet`, not the fileId from `knowledge doc upload`. For documents created via `knowledge create --doc-id`, the doc_id equals the fileId; for documents imported via `knowledge doc upload --index-id`, the doc_id may include a workspace suffix.
+- Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.
+- The output lists the ids actually deleted.
+
+#### Examples
+
+```bash
+bl knowledge doc delete --index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc delete --index-id idx-xxx --doc-id file-a --doc-id file-b --yes
+```
+
+### `bl knowledge doc import-oss`
+
+| Field              | Value                                                                               |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| **Name**           | `knowledge doc import-oss`                                                          |
+| **Description**    | Batch import files from an authorized OSS bucket into the data center               |
+| **Authentication** | API Key                                                                             |
+| **Usage**          | `bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--bucket <name>`     | string | yes      | Authorized OSS bucket name                                      |
+| `--region <id>`       | string | yes      | OSS region id (e.g. cn-beijing)                                 |
+| `--oss-key <key>`     | array  | yes      | OSS object key to import (repeatable, 1-10 per call)            |
+| `--category-id <id>`  | string | no       | Target data-center category (default: the default category)     |
+| `--tag <text>`        | array  | no       | File tag applied to every imported file (repeatable, up to 10)  |
+| `--overwrite`         | switch | no       | Overwrite files previously imported from the same OSS keys      |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- The bucket must be authorized to the platform service role beforehand; permission errors from the server are passed through with a pointer to check AliyunServiceRoleForBailian in the RAM console.
+- File names are derived from the OSS key basename.
+- --overwrite replaces the previously imported file and issues a NEW fileId (the old one becomes invalid) — verified live.
+
+#### Examples
+
+```bash
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
+```
+
+### `bl knowledge doc list`
+
+| Field              | Value                                                      |
+| ------------------ | ---------------------------------------------------------- |
+| **Name**           | `knowledge doc list`                                       |
+| **Description**    | List documents in a knowledge base with parse/index status |
+| **Authentication** | API Key                                                    |
+| **Usage**          | `bl knowledge doc list --index-id <id> [flags]`            |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                               |
+| `--page-number <n>`   | number | no       | Page number (default: 1)                                        |
+| `--page-size <n>`     | number | no       | Page size per request                                           |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Documents with status FAILED are highlighted in text mode — use the import job status command to inspect failures.
+- Page size defaults to 10 (server default), max 100.
+
+#### Examples
+
+```bash
+bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc list --index-id idx-xxx --page-size 100
+```
+
+### `bl knowledge doc status`
+
+| Field              | Value                                                           |
+| ------------------ | --------------------------------------------------------------- |
+| **Name**           | `knowledge doc status`                                          |
+| **Description**    | Check knowledge base import job status                          |
+| **Authentication** | API Key                                                         |
+| **Usage**          | `bl knowledge doc status --index-id <id> --job-id <id> [flags]` |
+
+#### Flags
+
+| Flag                        | Type   | Required | Description                                                     |
+| --------------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`           | string | yes      | Knowledge base ID                                               |
+| `--job-id <id>`             | string | yes      | Import job ID (ingestionId returned by import commands)         |
+| `--page-number <n>`         | number | no       | Page number (default: 1)                                        |
+| `--page-size <n>`           | number | no       | Page size per request                                           |
+| `--wait`                    | switch | no       | Poll until the job reaches a terminal state                     |
+| `--poll-interval <seconds>` | number | no       | Polling interval when waiting (default: 5)                      |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`           | string | no       | API key                                                         |
+| `--base-url <url>`          | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Both --index-id and --job-id are required (passing only one returns SystemError).
+- If you see a SystemError, the job may not exist — check the ingestion id in the document list output.
+- Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.
+
+#### Examples
+
+```bash
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
+```
+
+### `bl knowledge doc tag`
+
+| Field              | Value                                                     |
+| ------------------ | --------------------------------------------------------- |
+| **Name**           | `knowledge doc tag`                                       |
+| **Description**    | Batch update tags on data-center files                    |
+| **Authentication** | API Key                                                   |
+| **Usage**          | `bl knowledge doc tag --doc-id <id> --tag <text> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--doc-id <id>`       | array  | yes      | Data-center file ID to tag (repeatable, 1-20 per call)          |
+| `--tag <text>`        | array  | yes      | Tag applied to every --doc-id (repeatable, each up to 32 chars) |
+| `--mode <mode>`       | string | no       | Update mode: append (default) or overwrite                      |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- The same tag set is applied to every --doc-id; run the command multiple times for different tag sets.
+- Server limits: up to 100 tags per file, total tag length up to 700 chars, tag up to 32 chars.
+
+#### Examples
+
+```bash
+bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
+```
+
+### `bl knowledge doc upload`
+
+| Field              | Value                                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| **Name**           | `knowledge doc upload`                                                                           |
+| **Description**    | Upload local files or directories to the data center and optionally import into a knowledge base |
+| **Authentication** | API Key                                                                                          |
+| **Usage**          | `bl knowledge doc upload --file <path> [flags]`                                                  |
+
+#### Flags
+
+| Flag                        | Type   | Required | Description                                                                                                     |
+| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `--file <path>`             | array  | yes      | Local file or directory path (repeatable). Directories are scanned recursively; unsupported formats are skipped |
+| `--index-id <id>`           | string | no       | Import into this knowledge base after registration (one job for all files)                                      |
+| `--category-id <id>`        | string | no       | Target data-center category; defaults to the workspace default category                                         |
+| `--tag <text>`              | array  | no       | File tag (repeatable), applied to every uploaded file                                                           |
+| `--wait`                    | switch | no       | Poll the import job to a terminal state (needs --index-id)                                                      |
+| `--poll-interval <seconds>` | number | no       | Polling interval when waiting (default: 5)                                                                      |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                 |
+| `--api-key <key>`           | string | no       | API key                                                                                                         |
+| `--base-url <url>`          | string | no       | API base URL                                                                                                    |
+
+#### Notes
+
+- Pipeline: apply upload lease → PUT to OSS → register file → (with --index-id) create import job.
+- Without --category-id the workspace default category is resolved automatically.
+- Directories are scanned recursively; node_modules, .git, and similar are skipped automatically.
+- Multiple files are processed sequentially; on failure, already-registered file ids are listed in the error hint.
+
+#### Examples
+
+```bash
+bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
+```
+
+```bash
+bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge doc upload --file ./docs/ --dry-run --verbose
+```
+
+### `bl knowledge file delete`
+
+| Field              | Value                                             |
+| ------------------ | ------------------------------------------------- |
+| **Name**           | `knowledge file delete`                           |
+| **Description**    | Permanently delete a file from the data center    |
+| **Authentication** | API Key                                           |
+| **Usage**          | `bl knowledge file delete --file-id <id> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--file-id <id>`      | string | yes      | Data-center file ID to delete                                   |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Irreversible. If knowledge bases reference this file, their related document indexes become invalid.
+- To remove a document from a single knowledge base only, use the document delete command instead.
+
+#### Examples
+
+```bash
+bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge file delete --file-id file-xxx --yes
+```
+
+### `bl knowledge file get`
+
+| Field              | Value                                                       |
+| ------------------ | ----------------------------------------------------------- |
+| **Name**           | `knowledge file get`                                        |
+| **Description**    | Show data-center file details (size, MD5, tags, timestamps) |
+| **Authentication** | API Key                                                     |
+| **Usage**          | `bl knowledge file get --file-id <id> [flags]`              |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--file-id <id>`      | string | yes      | Data-center file ID                                             |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Examples
+
+```bash
+bl knowledge file get --file-id file-xxx --workspace-id ws-xxx
+```
+
+### `bl knowledge file list`
+
+| Field              | Value                                               |
+| ------------------ | --------------------------------------------------- |
+| **Name**           | `knowledge file list`                               |
+| **Description**    | List files in a data-center category                |
+| **Authentication** | API Key                                             |
+| **Usage**          | `bl knowledge file list --category-id <id> [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                            |
+| ---------------------- | ------ | -------- | ---------------------------------------------------------------------- |
+| `--category-id <id>`   | string | yes      | Category to list (find ids via the category list command); exact match |
+| `--name <text>`        | string | no       | Filter by exact file name without its extension (a.md → pass a)        |
+| `--file-id <id>`       | array  | no       | Filter by exact file ID (repeatable)                                   |
+| `--next-token <token>` | string | no       | Cursor for the next page (from previous output)                        |
+| `--max-result <n>`     | number | no       | Items per page                                                         |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)        |
+| `--api-key <key>`      | string | no       | API key                                                                |
+| `--base-url <url>`     | string | no       | API base URL                                                           |
+
+#### Notes
+
+- A real category id is required — the default value is not resolved here. Find the id via the category list command.
+- --name matches the exact file name without its extension (for a.md pass a); partial keywords return no results.
+- Pagination is cursor-based: reuse the printed next token to continue.
+
+#### Examples
+
+```bash
+bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge file list --category-id cate-xxx --name report
+```
+
+### `bl knowledge info`
+
+| Field              | Value                                       |
+| ------------------ | ------------------------------------------- |
+| **Name**           | `knowledge info`                            |
+| **Description**    | Show knowledge base configuration details   |
+| **Authentication** | API Key                                     |
+| **Usage**          | `bl knowledge info --index-id <id> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                               |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Indexing settings are immutable; changing them requires recreating the knowledge base.
+
+#### Examples
+
+```bash
+bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
+```
+
+### `bl knowledge list`
+
+| Field              | Value                                 |
+| ------------------ | ------------------------------------- |
+| **Name**           | `knowledge list`                      |
+| **Description**    | List knowledge bases in the workspace |
+| **Authentication** | API Key                               |
+| **Usage**          | `bl knowledge list [flags]`           |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--name <text>`       | string | no       | Filter by knowledge base name (fuzzy match, 1-20 chars)         |
+| `--page-number <n>`   | number | no       | Page number (default: 1)                                        |
+| `--page-size <n>`     | number | no       | Page size per request                                           |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Auth: uses DashScope API Key (Bearer token).
+- `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or config workspace_id.
+- Use the returned id as --index-id in knowledge base / document management commands.
+
+#### Examples
+
+```bash
+bl knowledge list --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge list --name demo --page-number 2 --page-size 50
+```
+
 ### `bl knowledge retrieve`
 
 | Field              | Value                                                                     |
@@ -103,22 +932,22 @@ bl knowledge retrieve --index-id idx_xxx --query "RAG retrieval" --rerank --rera
 
 #### Flags
 
-| Flag                     | Type   | Required | Description                                                                                                                                                                  |
-| ------------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--query <text>`         | string | yes      | Search query text (required, cannot be empty)                                                                                                                                |
-| `--agent-id <id>`        | string | yes      | Retrieval service ID (find in console knowledge retrieval page)                                                                                                              |
-| `--workspace-id <id>`    | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                                                                              |
-| `--image <url>`          | array  | no       | Image URL for multimodal retrieval (repeatable)                                                                                                                              |
-| `--query-history <json>` | string | no       | User conversation history JSON for context understanding and query rewriting. Format: '[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is..."}]' |
-| `--api-key <key>`        | string | no       | API key                                                                                                                                                                      |
-| `--base-url <url>`       | string | no       | API base URL                                                                                                                                                                 |
+| Flag                        | Type   | Required | Description                                                                                                        |
+| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--query <text>`            | string | yes      | Search query text (required, cannot be empty)                                                                      |
+| `--agent-id <id>`           | string | yes      | Retrieval service ID (find in console knowledge retrieval page)                                                    |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                    |
+| `--agent-version <version>` | string | no       | Service version to call: beta (draft for debugging) or a published number; default is the latest published version |
+| `--image <url>`             | array  | no       | Image URL for multimodal retrieval (repeatable)                                                                    |
+| `--api-key <key>`           | string | no       | API key                                                                                                            |
+| `--base-url <url>`          | string | no       | API base URL                                                                                                       |
 
 #### Notes
 
 - Retrieval scope and strategy (multi-index weighting, routing, reranking, etc.) are driven by the agent_id service config. Only query and agent_id are required.
 - Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
 - `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.
-- `--query-history` passes prior conversation turns; the server rewrites the query based on context to improve retrieval relevance.
+- `--agent-version beta` calls the draft config for debugging before it is deployed.
 
 #### Examples
 
@@ -130,6 +959,337 @@ bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-
 bl knowledge search --api-key $DASHSCOPE_API_KEY --query "test search" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
 ```
 
+### `bl knowledge service copy`
+
+| Field              | Value                                                       |
+| ------------------ | ----------------------------------------------------------- |
+| **Name**           | `knowledge service copy`                                    |
+| **Description**    | Copy a service into a new draft (name gets a copy\_ prefix) |
+| **Authentication** | API Key                                                     |
+| **Usage**          | `bl knowledge service copy --agent-id <id> [flags]`         |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--agent-id <id>`     | string | yes      | Source service (agent) ID to copy                               |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- The copy starts as a beta draft; test it with --agent-version beta, then deploy to publish.
+- Requires the knowledge-base create permission in the workspace.
+
+#### Examples
+
+```bash
+bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+### `bl knowledge service create`
+
+| Field              | Value                                                                      |
+| ------------------ | -------------------------------------------------------------------------- |
+| **Name**           | `knowledge service create`                                                 |
+| **Description**    | Create a retrieval / Q&A service (initial status: draft, version: beta)    |
+| **Authentication** | API Key                                                                    |
+| **Usage**          | `bl knowledge service create --name <text> --scene <chat\|search> [flags]` |
+
+#### Flags
+
+| Flag                   | Type   | Required | Description                                                       |
+| ---------------------- | ------ | -------- | ----------------------------------------------------------------- |
+| `--name <text>`        | string | yes      | Service name (up to 200 chars, unique per scene in the workspace) |
+| `--scene <scene>`      | string | yes      | Service scene: chat (Q&A) or search (retrieval)                   |
+| `--description <text>` | string | no       | Service description (up to 1000 chars)                            |
+| `--index-id <id>`      | string | no       | Bind this knowledge base; other settings use server defaults      |
+| `--workspace-id <id>`  | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)   |
+| `--api-key <key>`      | string | no       | API key                                                           |
+| `--base-url <url>`     | string | no       | API base URL                                                      |
+
+#### Notes
+
+- Without an explicit configuration the server applies its default agent settings.
+- The draft (beta) version can be tested via --agent-version beta on search/chat before deploying.
+- Requires the knowledge-base create permission in the workspace.
+
+#### Examples
+
+```bash
+bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service create --name my-search --scene search --index-id idx-xxx
+```
+
+### `bl knowledge service delete`
+
+| Field              | Value                                                      |
+| ------------------ | ---------------------------------------------------------- |
+| **Name**           | `knowledge service delete`                                 |
+| **Description**    | Delete a retrieval / Q&A service (soft delete, idempotent) |
+| **Authentication** | API Key                                                    |
+| **Usage**          | `bl knowledge service delete --agent-id <id> [flags]`      |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                     |
+| --------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--agent-id <id>`     | string | yes      | Service (agent) ID                                              |
+| `--yes`               | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`     | string | no       | API key                                                         |
+| `--base-url <url>`    | string | no       | API base URL                                                    |
+
+#### Notes
+
+- Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.
+- Idempotent — deleting an already-deleted service does not fail.
+- Requires the knowledge-base delete permission in the workspace.
+
+#### Examples
+
+```bash
+bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service delete --agent-id aid-xxx --yes
+```
+
+### `bl knowledge service deploy`
+
+| Field              | Value                                                 |
+| ------------------ | ----------------------------------------------------- |
+| **Name**           | `knowledge service deploy`                            |
+| **Description**    | Publish the beta draft of a service as a new version  |
+| **Authentication** | API Key                                               |
+| **Usage**          | `bl knowledge service deploy --agent-id <id> [flags]` |
+
+#### Flags
+
+| Flag                    | Type   | Required | Description                                                     |
+| ----------------------- | ------ | -------- | --------------------------------------------------------------- |
+| `--agent-id <id>`       | string | yes      | Service (agent) ID                                              |
+| `--version-desc <text>` | string | no       | Description for the newly published version                     |
+| `--yes`                 | switch | no       | Skip the confirmation prompt                                    |
+| `--workspace-id <id>`   | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
+| `--api-key <key>`       | string | no       | API key                                                         |
+| `--base-url <url>`      | string | no       | API base URL                                                    |
+
+#### Notes
+
+- The version number auto-increments; status becomes deployed.
+- Publishing affects live callers — the confirmation prompt guards against accidents.
+- Requires the knowledge-base modify permission in the workspace.
+
+#### Examples
+
+```bash
+bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service deploy --agent-id aid-xxx --version-desc 'tuned rerank params' --yes
+```
+
+### `bl knowledge service get`
+
+| Field              | Value                                                            |
+| ------------------ | ---------------------------------------------------------------- |
+| **Name**           | `knowledge service get`                                          |
+| **Description**    | Show service (agent) details including per-version configuration |
+| **Authentication** | API Key                                                          |
+| **Usage**          | `bl knowledge service get --agent-id <id> [flags]`               |
+
+#### Flags
+
+| Flag                        | Type   | Required | Description                                                                     |
+| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
+| `--agent-id <id>`           | string | yes      | Service (agent) ID                                                              |
+| `--agent-version <version>` | string | no       | Specific version to inspect (beta or a published number); omit for all versions |
+| `--workspace-id <id>`       | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                 |
+| `--api-key <key>`           | string | no       | API key                                                                         |
+| `--base-url <url>`          | string | no       | API base URL                                                                    |
+
+#### Notes
+
+- Without --agent-version all versions are returned (beta draft plus published numbers).
+- The version value is passed through as-is; the valid set is server-side state.
+
+#### Examples
+
+```bash
+bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service get --agent-id aid-xxx --agent-version beta
+```
+
+### `bl knowledge service list`
+
+| Field              | Value                                                      |
+| ------------------ | ---------------------------------------------------------- |
+| **Name**           | `knowledge service list`                                   |
+| **Description**    | List retrieval / Q&A services (agents) in the workspace    |
+| **Authentication** | API Key                                                    |
+| **Usage**          | `bl knowledge service list --scene <chat\|search> [flags]` |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                             |
+| --------------------- | ------ | -------- | ----------------------------------------------------------------------- |
+| `--scene <scene>`     | string | yes      | Service scene: chat (Q&A) or search (retrieval). Required by the server |
+| `--status <status>`   | string | no       | Filter by status: draft, deployed (includes edited) or deleted          |
+| `--name <text>`       | string | no       | Filter by service name (fuzzy match)                                    |
+| `--agent-id <id>`     | string | no       | Filter by exact agent ID                                                |
+| `--index-id <id>`     | string | no       | Filter by exact linked knowledge base (pipeline) ID                     |
+| `--page-number <n>`   | number | no       | Page number (default: 1)                                                |
+| `--page-size <n>`     | number | no       | Page size per request                                                   |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)         |
+| `--api-key <key>`     | string | no       | API key                                                                 |
+| `--base-url <url>`    | string | no       | API base URL                                                            |
+
+#### Notes
+
+- A scene (chat or search) is required — run once per scene to see both.
+- Use the returned agent_id with the search or chat commands, or with service management commands.
+
+#### Examples
+
+```bash
+bl knowledge service list --scene chat --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service list --scene search --status deployed
+```
+
+### `bl knowledge service update`
+
+| Field              | Value                                                   |
+| ------------------ | ------------------------------------------------------- |
+| **Name**           | `knowledge service update`                              |
+| **Description**    | Update service name, description or draft configuration |
+| **Authentication** | API Key                                                 |
+| **Usage**          | `bl knowledge service update --agent-id <id> [flags]`   |
+
+#### Flags
+
+| Flag                           | Type   | Required | Description                                                                                                                          |
+| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `--agent-id <id>`              | string | yes      | Service (agent) ID                                                                                                                   |
+| `--name <text>`                | string | no       | New service name (up to 200 chars)                                                                                                   |
+| `--description <text>`         | string | no       | New service description (up to 1000 chars)                                                                                           |
+| `--agent-version <version>`    | string | no       | Target version (default: beta draft). Published versions only accept --version-desc                                                  |
+| `--version-desc <text>`        | string | no       | Version description                                                                                                                  |
+| `--policy <policy>`            | string | no       | Agent policy: turbo (fast) or agentic (multi-turn)                                                                                   |
+| `--model <name>`               | string | no       | Generation model code (must be in the platform allowlist)                                                                            |
+| `--temperature <n>`            | number | no       | Sampling temperature, range 0-2                                                                                                      |
+| `--max-llm-calls <n>`          | number | no       | Max LLM calls per request, range 1-30                                                                                                |
+| `--enable-session-file <bool>` | string | no       | Enable session files: true or false                                                                                                  |
+| `--enable-refusal <bool>`      | string | no       | Enable refusal answers: true or false                                                                                                |
+| `--enable-anti-leak <bool>`    | string | no       | Enable anti prompt-leak: true or false                                                                                               |
+| `--enable-rich-text <bool>`    | string | no       | Enable rich text output: true or false                                                                                               |
+| `--enable-citation <bool>`     | string | no       | Enable citations: true or false                                                                                                      |
+| `--config-file <path>`         | string | no       | JSON file replacing the whole agent_config (for nested settings like kb_search_configs); mutually exclusive with scalar config flags |
+| `--workspace-id <id>`          | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                                                                      |
+| `--api-key <key>`              | string | no       | API key                                                                                                                              |
+| `--base-url <url>`             | string | no       | API base URL                                                                                                                         |
+
+#### Notes
+
+- Configuration changes only apply to the beta draft; published versions accept --version-desc only.
+- To change the configuration of a published version, first update the beta draft (this command without --agent-version or with --agent-version beta), then run service deploy to publish a new version.
+- Scalar config flags merge into the current draft config (read-merge-write); --config-file replaces the whole config and is mutually exclusive with them.
+- After updating the draft, verify with --agent-version beta on search/chat, then deploy.
+- Requires the knowledge-base modify permission in the workspace.
+
+#### Examples
+
+```bash
+bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge service update --agent-id aid-xxx --config-file ./agent-config.json
+```
+
+```bash
+bl knowledge service update --agent-id aid-xxx --agent-version 1 --version-desc 'first stable release'
+```
+
+### `bl knowledge stats`
+
+| Field              | Value                                               |
+| ------------------ | --------------------------------------------------- |
+| **Name**           | `knowledge stats`                                   |
+| **Description**    | Show knowledge base storage and QPS monitoring data |
+| **Authentication** | API Key                                             |
+| **Usage**          | `bl knowledge stats --index-id <id> [flags]`        |
+
+#### Flags
+
+| Flag                  | Type   | Required | Description                                                                        |
+| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
+| `--index-id <id>`     | string | yes      | Knowledge base ID                                                                  |
+| `--start <time>`      | string | no       | Range start: Unix seconds or ISO date, must be in the past (default: 24 hours ago) |
+| `--end <time>`        | string | no       | Range end: Unix seconds or ISO date, must be in the past (default: now)            |
+| `--workspace-id <id>` | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)                    |
+| `--api-key <key>`     | string | no       | API key                                                                            |
+| `--base-url <url>`    | string | no       | API base URL                                                                       |
+
+#### Notes
+
+- Defaults to the last 24 hours when --start/--end are omitted.
+- Timestamps are normalized to epoch seconds as required by the server.
+- Future timestamps are rejected for --start and clamped to now for --end, since the monitor API only returns past data.
+
+#### Examples
+
+```bash
+bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx
+```
+
+```bash
+bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
+```
+
+### `bl knowledge update`
+
+| Field              | Value                                                       |
+| ------------------ | ----------------------------------------------------------- |
+| **Name**           | `knowledge update`                                          |
+| **Description**    | Update knowledge base name, description or rerank threshold |
+| **Authentication** | API Key                                                     |
+| **Usage**          | `bl knowledge update --index-id <id> [flags]`               |
+
+#### Flags
+
+| Flag                         | Type   | Required | Description                                                           |
+| ---------------------------- | ------ | -------- | --------------------------------------------------------------------- |
+| `--index-id <id>`            | string | yes      | Knowledge base ID                                                     |
+| `--name <text>`              | string | no       | New knowledge base name (1-20 chars)                                  |
+| `--description <text>`       | string | no       | New knowledge base description                                        |
+| `--rerank-min-score <score>` | number | no       | Rerank minimum score threshold, range 0-1 (chunks below are filtered) |
+| `--workspace-id <id>`        | string | no       | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID)       |
+| `--api-key <key>`            | string | no       | API key                                                               |
+| `--base-url <url>`           | string | no       | API base URL                                                          |
+
+#### Notes
+
+- Indexing settings (embedding model, chunk size, etc.) are immutable — recreate the knowledge base to change them.
+
+#### Examples
+
+```bash
+bl knowledge update --index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx
+```
+
 ```bash
-bl knowledge search --query "How does it work" --agent-id aid-xxx --workspace-id ws-xxx --query-history '[{"role":"user","content":"What is RAG"},{"role":"assistant","content":"RAG is retrieval-augmented generation"}]'
+bl knowledge update --index-id idx-xxx --rerank-min-score 0.3
 ```
diff --git a/skills/bailian-finetune/SKILL.md b/skills/bailian-finetune/SKILL.md
index 9f3180fe..58f5a044 100644
--- a/skills/bailian-finetune/SKILL.md
+++ b/skills/bailian-finetune/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: bailian-finetune
 metadata:
-  version: "1.15.1"
+  version: "1.16.0"
   requires:
     bins: ["bl"]
 description: >-
diff --git a/skills/bailian-gen/SKILL.md b/skills/bailian-gen/SKILL.md
index 22ef7f31..872b53b9 100644
--- a/skills/bailian-gen/SKILL.md
+++ b/skills/bailian-gen/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: bailian-gen
 metadata:
-  version: "1.15.1"
+  version: "1.16.0"
   requires:
     bins: ["bl"]
 description: >-
diff --git a/skills/bailian-managed-agent/SKILL.md b/skills/bailian-managed-agent/SKILL.md
index fa36588b..316a8d24 100644
--- a/skills/bailian-managed-agent/SKILL.md
+++ b/skills/bailian-managed-agent/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: bailian-managed-agent
 metadata:
-  version: "1.15.1"
+  version: "1.16.0"
   requires:
     bins: ["bl"]
 description: >-
diff --git a/skills/bailian-protocol/SKILL.md b/skills/bailian-protocol/SKILL.md
index 459e8fa8..5405c5b4 100644
--- a/skills/bailian-protocol/SKILL.md
+++ b/skills/bailian-protocol/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: bailian-protocol
 metadata:
-  version: "1.15.1"
+  version: "1.16.0"
   requires:
     bins: ["bl"]
 description: >-