refactor(commands): remove deprecated retrieve command and update documentation

- Deleted the `knowledge retrieve` command, which is now deprecated in favor of `knowledge search`.
- Updated relevant documentation to reflect the removal of the retrieve command and to clarify the usage of the search command.
- Adjusted command references in various files to ensure consistency and accuracy in the CLI interface.
- Added tests to verify that attempts to use the removed command are correctly rejected.

Author: clark-fc

AGENTS.md

@@ -41,7 +41,7 @@ Skill / 命令手册随 `skills/bailian-*/` 经 `bl skill init` 安装（装齐
 约定:
 
 - 命令实现文件路径仍按能力放置:`packages/commands/src/commands/text/chat.ts`
-- 产品命令路径由入口 map 决定:同一个实现可暴露为 `bl knowledge retrieve` 或 `kscli retrieve`
+- 产品命令路径由入口 map 决定:同一个实现可暴露为 `bl knowledge search` 或 `kscli search`
 - `defineCommand` 只写命令元数据与逻辑: `auth`、`flags`、`usageArgs`、`exampleArgs`、`validate`、`run`
 - `usageArgs` / `exampleArgs` 不写 `bl` 或 `kscli` 前缀;runtime / reference 生成器按产品路径补前缀
 - 不再使用 `catalog.ts` 作为登记处;新增/重命名命令必须同时看命令库导出和产品入口 map

docs/agents/command-add-remove.md

@@ -13,11 +13,11 @@
 
 ```
 实现文件:
-  packages/commands/src/commands/knowledge/retrieve.ts
-    ↓ packages/commands/src/index.ts export { default as knowledgeRetrieve }
+  packages/commands/src/commands/knowledge/search.ts
+    ↓ packages/commands/src/index.ts export { default as knowledgeSearch }
 产品入口:
-  packages/cli/src/commands.ts  "knowledge retrieve": knowledgeRetrieve  ↔ bl knowledge retrieve
-  packages/kscli/src/main.ts    "retrieve": knowledgeRetrieve             ↔ kscli retrieve
+  packages/cli/src/commands.ts  "knowledge search": knowledgeSearch  ↔ bl knowledge search
+  packages/kscli/src/main.ts    "search": knowledgeSearch             ↔ kscli search
 ```
 
 常见路径形态:
@@ -43,7 +43,7 @@ packages/commands/src/index.ts
         ↓
 ┌──────────────────────────────┬──────────────────────────────┐
 │ packages/cli/src/commands.ts │ packages/kscli/src/main.ts   │
-│ { "text chat": textChat }    │ { "retrieve": knowledge... } │
+│ { "text chat": textChat }    │ { "search": knowledge... } │
 └──────────────┬───────────────┴──────────────┬───────────────┘
                ↓                              ↓
         createCli(commands, identity)  →  runtime registry/help/middleware

docs/knowledge/knowledge-cli-guide.md

@@ -32,7 +32,7 @@
 - **Chunk 级运维**：直接增删改查知识库中的内容切片
 - **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
 - **数据中心管理**：文件、集合（connector）、分类的增删查
-- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
+- **检索与对话**：语义检索（search）、多轮对话（chat）
 
 共 34 个子命令，按功能域分为 7 组。所有命令均使用 DashScope API Key 鉴权。
 
@@ -659,19 +659,7 @@ kscli category delete --category-id <id> [flags]
 
 ### 检索与对话
 
-> 📖 [完整手册](knowledge/search-chat.md) — 3 个命令
-
-#### `kscli retrieve`
-
-从知识库检索（已废弃，请用 `search` 替代）。
-
-```bash
-kscli retrieve --index-id <id> --query <text> [flags]
-```
-
-→ [完整参数与示例](knowledge/search-chat.md#bl-knowledge-retrieve)
-
----
+> 📖 [完整手册](knowledge/search-chat.md) — 2 个命令
 
 #### `kscli search`
 
@@ -742,12 +730,6 @@ bl config set workspace_id ws-xxx
 
 **解决**：始终用 `doc list --quiet` 获取 `doc_id`。
 
-### retrieve 已废弃
-
-**问题**：`retrieve` 命令输出废弃警告。
-
-**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
-
 ### OSS 导入权限错误
 
 **报错**：服务端返回权限相关错误。
@@ -817,6 +799,5 @@ bl config set workspace_id ws-xxx
 | `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`                                   |

docs/knowledge/search-chat.md

@@ -1,70 +1,11 @@
 # 检索与对话命令手册
 
-以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
+以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。
 
 > **通用约定**（鉴权、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 检索）。
@@ -108,7 +49,7 @@ json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
 
 - 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
 - `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
-- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
+- `search` 通过 agent_id 驱动检索策略，支持多知识库、路由、rerank 等。
 
 **示例**
 

docs/kscli/kscli-cli-guide.md

@@ -33,7 +33,7 @@
 - **Chunk 级运维**：直接增删改查知识库中的内容切片
 - **检索服务管理**：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
 - **数据中心管理**：文件、集合（connector）、分类的增删查
-- **检索与对话**：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
+- **检索与对话**：语义检索（search）、多轮对话（chat）
 - **配置与维护**：查看/修改本地配置、自更新 CLI
 
 共 37 个命令：34 个知识库命令（按功能域分为 7 组）+ `config show` / `config set` / `update`。所有知识库命令均使用 DashScope API Key 鉴权。
@@ -676,19 +676,7 @@ kscli category delete --category-id <id> [flags]
 
 ### 检索与对话
 
-> 📖 [完整手册](search-chat.md) — 3 个命令
-
-#### `kscli retrieve`
-
-从知识库检索（已废弃，请用 `search` 替代）。
-
-```bash
-kscli retrieve --index-id <id> --query <text> [flags]
-```
-
-→ [完整参数与示例](search-chat.md#kscli-retrieve)
-
----
+> 📖 [完整手册](search-chat.md) — 2 个命令
 
 #### `kscli search`
 
@@ -846,12 +834,6 @@ kscli config set --key workspace_id --value ws-xxx
 
 **解决**：始终用 `kscli doc list --quiet` 获取 `doc_id`。
 
-### retrieve 已废弃
-
-**问题**：`retrieve` 命令输出废弃警告。
-
-**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
-
 ### OSS 导入权限错误
 
 **报错**：服务端返回权限相关错误。
@@ -921,7 +903,6 @@ kscli config set --key workspace_id --value ws-xxx
 | `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`                                   |
 | `kscli config show`       | 查看配置     | `--output`                                                  |

docs/kscli/search-chat.md

@@ -1,70 +1,11 @@
 # 检索与对话命令手册
 
-以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
+以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。
 
 > **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
 
 ---
 
-#### `kscli retrieve`
-
-从知识库检索（已废弃，请用 `search` 替代）。
-
-**用法**
-
-```bash
-kscli 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
-# 基础检索
-kscli retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
-
-# 启用 rerank
-kscli retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
-```
-
----
-
 #### `kscli search`
 
 对知识库执行语义检索（RAG 检索）。
@@ -108,7 +49,7 @@ json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
 
 - 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
 - `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
-- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
+- `search` 通过 agent_id 驱动检索策略，支持多知识库、路由、rerank 等。
 
 **示例**
 

packages/cli/src/commands.ts

@@ -36,7 +36,6 @@ import {
   memoryProfileUpdate,
   memoryProfileDelete,
   memoryProfileGet,
-  knowledgeRetrieve,
   knowledgeSearch,
   knowledgeChat,
   knowledgeKbList,
@@ -316,7 +315,6 @@ export const commands: Record<string, AnyCommand> = {
   "memory profile update": memoryProfileUpdate,
   "memory profile delete": memoryProfileDelete,
   "memory profile get": memoryProfileGet,
-  "knowledge retrieve": knowledgeRetrieve,
   "knowledge search": knowledgeSearch,
   "knowledge chat": knowledgeChat,
   "knowledge list": knowledgeKbList,

packages/cli/tests/e2e/registry.smoke.e2e.test.ts

@@ -86,3 +86,8 @@ describe("e2e: bl registry smoke", () => {
     );
   });
 });
+
+test("removed retrieve command is rejected", async () => {
+  const { exitCode } = await runCliSmoke(["knowledge", "retrieve", "--help"]);
+  expect(exitCode).toBe(2);
+});