检索服务（也称 agent）是知识库的检索入口，承载模型、策略、重排等配置，在 search 和 chat 命令中通过 --agent-id 指定。服务分 search（检索）和 chat（问答）两种场景。本组共 7 个命令。
鉴权、业务空间 ID、全局参数、输出格式、二次确认和干跑模式等通用约定见 CLI 概述。以下示例默认已通过配置文件设置业务空间 ID。
版本模型
服务的配置变更遵循草稿到发布的流程：
| 状态 | 说明 |
|---|
draft | 服务刚创建，只有 beta 草稿，尚未发布 |
deployed | 已发布至少一个版本，线上调用走最新发布版本 |
edited | 已发布后又修改了 beta 草稿，线上仍走已发布版本 |
deleted | 已删除 |
search 或 chat 加 --agent-version beta 验证草稿效果，确认后通过 service deploy 发布为正式版本，版本号自动递增。
kscli service list
列出业务空间中的检索或问答服务。
kscli service list --scene <chat|search> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--scene <chat｜search> | string | 是 | 服务场景，chat（问答）或 search（检索） |
--status <status> | string | 否 | 按状态过滤，draft、deployed（含 edited）或 deleted |
--name <text> | string | 否 | 按服务名称模糊过滤 |
--agent-id <id> | string | 否 | 按服务 ID 精确过滤 |
--index-id <id> | string | 否 | 按关联的知识库 ID 过滤 |
--page-number <n> | number | 否 | 页码，默认 1 |
--page-size <n> | number | 否 | 每页条数，默认 10，范围 1–100 |
aid-xxx deployed 2 my-qa (kb: my-kb)
total: 1
Use an agent_id above with the chat command.
--scene 自动提示应使用 search 还是 chat 命令消费。
quiet 模式每行输出一个服务 ID。json 模式返回完整结果。
--scene 为必填参数，查看两种场景的服务需分别执行。
示例
# 列出问答服务
kscli service list --scene chat
# 只看已发布的检索服务
kscli service list --scene search --status deployed
kscli service get
查看服务详情，含各版本的配置。
kscli service get --agent-id <id> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--agent-id <id> | string | 是 | 服务 ID |
--agent-version <version> | string | 否 | 指定查看的版本，beta 或已发布版本号。不传则返回所有版本 |
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 结果。
配合 --output json 可以导出当前配置，编辑后用 service update --config-file 整体写回。
示例
# 查看全部版本
kscli service get --agent-id aid-xxx
# 只看 beta 草稿
kscli service get --agent-id aid-xxx --agent-version beta
kscli service create
创建检索或问答服务，初始状态为 draft，版本为 beta。
kscli service create --name <text> --scene <chat|search> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--name <text> | string | 是 | 服务名称，最多 200 字符，同一场景下业务空间内唯一 |
--scene <chat｜search> | string | 是 | 服务场景，chat（问答）或 search（检索） |
--description <text> | string | 否 | 服务描述，最多 1000 字符 |
--index-id <id> | string | 否 | 绑定此知识库，其他配置使用服务端默认值 |
created: aid-xxx (status: draft, version: beta)
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
quiet 模式输出服务 ID。json 模式返回完整结果。
注意事项
- 不指定
--index-id 时使用默认配置创建，后续可通过 service update --config-file 绑定知识库。
- 新建服务只有 beta 草稿，发布前
search 和 chat 的正式调用无法命中，需加 --agent-version beta 测试。
- 需要业务空间的知识库创建权限。
示例
# 创建问答服务
kscli service create --name my-qa --scene chat
# 创建检索服务并绑定知识库
kscli service create --name my-search --scene search --index-id idx-xxx
kscli service update
更新服务名称、描述或草稿配置。
kscli service update --agent-id <id> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--agent-id <id> | string | 是 | 服务 ID |
--name <text> | string | 否 | 新名称，最多 200 字符 |
--description <text> | string | 否 | 新描述，最多 1000 字符 |
--agent-version <version> | string | 否 | 目标版本，默认 beta 草稿。已发布版本只接受 --version-desc |
--version-desc <text> | string | 否 | 版本描述 |
--policy <policy> | string | 否 | 服务策略，turbo（快速）或 agentic（多轮） |
--model <name> | string | 否 | 生成模型名称，须在平台支持列表中 |
--temperature <n> | number | 否 | 采样温度，范围 0–2 |
--max-llm-calls <n> | number | 否 | 单次请求的最大模型调用次数，范围 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 文件整体替换服务配置，可设置知识库绑定等嵌套字段；与上述单项配置参数互斥 |
- 至少提供一个更新项，否则报错
Nothing to update
--config-file 与单项配置参数（--policy、--model、--temperature 等）互斥- 已发布版本只接受
--version-desc，不接受配置变更
- 布尔参数只能传
true 或 false
输出
updated: aid-xxx
Draft config changed — verify with --agent-version beta, then deploy.
quiet 模式无输出。json 模式返回完整结果。
注意事项
- 配置变更只作用于 beta 草稿，不影响线上调用，直到执行
service deploy。
- 使用单项配置参数时，未指定的其他配置项自动保持不变。
--config-file 整体替换配置，未在 JSON 中出现的字段会被重置为默认值。建议先用 service get --output json 导出当前配置作为编辑起点。
示例
# 调整温度
kscli service update --agent-id aid-xxx --temperature 0.7
# 用 JSON 文件替换整个配置
kscli service update --agent-id aid-xxx --config-file ./agent-config.json
# 给已发布的版本 1 补充描述
kscli service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
kscli service deploy
将 beta 草稿发布为新版本。
kscli service deploy --agent-id <id> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--agent-id <id> | string | 是 | 服务 ID |
--version-desc <text> | string | 否 | 新版本的描述说明 |
--yes | switch | 否 | 跳过确认提示 |
deployed: aid-xxx version 2
quiet 模式输出新版本号。json 模式返回完整结果。
发布会立即改变线上调用方的行为。如果服务当前状态为 edited（已发布后又修改了草稿），确认提示会额外警告发布将覆盖线上行为。建议先用 --agent-version beta 完成验证再发布。
deployed。需要业务空间的知识库修改权限。
示例
# 交互确认后发布
kscli service deploy --agent-id aid-xxx
# 带描述并跳过确认
kscli service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
kscli service delete
删除检索或问答服务。
kscli service delete --agent-id <id> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--agent-id <id> | string | 是 | 服务 ID |
--yes | switch | 否 | 跳过确认提示 |
deleted: aid-xxx (status: deleted)
quiet 模式无输出。json 模式返回完整结果。
删除不可撤销，该 agent_id 不再可用于 search 和 chat 调用，所有引用它的应用会立即失败。如果服务状态为 deployed 或 edited，确认提示会额外警告该服务正在线上运行。
# 交互确认后删除
kscli service delete --agent-id aid-xxx
# 跳过确认
kscli service delete --agent-id aid-xxx --yes
kscli service copy
复制服务为新草稿，名称自动加 copy_ 前缀。
kscli service copy --agent-id <id> [flags]
| 参数 | 类型 | 必填 | 说明 |
|---|
--agent-id <id> | string | 是 | 源服务 ID |
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 模式输出新服务 ID。json 模式返回完整结果。
副本初始为 draft 状态的 beta 草稿，验证后需执行 service deploy 才能对正式调用生效。适合在不影响线上服务的前提下试验新配置。需要业务空间的知识库创建权限。
示例
kscli service copy --agent-id aid-source