百炼知识库管理（bl）

检索面与管理面的分工：查知识用 kb_search（取证据）/ kb_chat（成品问答）原生工具；本 skill 只覆盖管理长尾——知识库全生命周期、文档、检索服务、Chunk、数据中心。

本 skill 不负责判断何时该检索。可用检索服务的清单（含 agent_id）由插件自动注入到会话上下文里，kb_search / kb_chat 直接取用；不需要为了检索先加载本 skill。

检索服务清单的行为语义

• 清单由插件从百炼 API 拉取后缓存，按会话周期性刷新（约 30 分钟），只含 deployed 状态的服务；
• 刚用 bl 新建或部署的服务不会立刻出现在清单里。不用等刷新——命令输出里刚拿到的 agent_id 直接可用；
• 服务很多时清单只列最近修改的若干条并标明总数。要找特定服务用 bl knowledge service list --scene search --name <关键词>；
• 清单里确实没有能回答用户问题的服务时，如实告知用户，不要挑一个最像的 agent_id 去试。

执行入口与配置

下文 bl knowledge … 是命令语法示例，实际操作一律通过 kb_manage，把 bl knowledge 后面的部分拆成参数数组。例如 bl knowledge service list --scene search 对应 kb_manage({"args":["service","list","--scene","search"]})。

不要通过 shell 直接运行知识库命令，不要读取密钥或使用 bl auth login / bl config set。插件自动使用 dsh 当前凭据、Workspace 和固定端点；缺配置时引导用户在 dsh 插件设置页填写。参数不得包含 --api-key、--workspace-id、--base-url 或 --config。

使用 kb_manage({"args":["list","--help"]}) 检查命令。若宿主未安装 bl，安装 bailian-cli 后重试。参数不确定时先查对应命令 --help，不要猜。

涉及删除等需要确认的操作，保留 CLI 原有确认机制；出现 requires_confirmation 时向用户确认，不自动补 --yes。

何时用哪个命令

核心工作流：建库到可检索

bl knowledge doc upload --file ./docs/                # 1. 上传本地文件/目录 → 得 fileId
bl knowledge create --name my-kb --description '产品文档' --doc-id <fileId> --wait                # 2. 建库并导入 → 得 index-id (pipelineId)
bl knowledge service create --name my-search --scene search --index-id <index-id>   # 3. 建检索服务 → 得 agent-id（draft）
bl knowledge service deploy --agent-id <agent-id>                           # 4. 发布服务（此后可被默认版本调用）
bl knowledge service list --scene search --status deployed                  # 5. 确认服务可见

部署完成后用原生工具 kb_search 带该 agent_id 验证检索；若要在部署前调试草稿配置，用 bl knowledge search --agent-id <id> --agent-version beta。

已有文件再入库的简写：bl knowledge doc upload --file ./a.md --index-id <index-id> --wait（上传+导入一步完成）。

ID 速查（极易混淆）

命令参考

执行不熟悉的命令前，跑 bl <命令> --help 查看完整 Usage / Flags / Notes / Examples。不要猜 flag。 全部命令支持 --output json（结构化输出）、--dry-run（预览请求）、--quiet、--verbose。

危险与不可逆操作

执行以下操作前须向用户确认，脚本化时才用 --yes 跳过交互确认：

• knowledge delete：不可逆，库和全部索引内容永久删除（数据中心源文件保留）。
• file delete：不可逆，且引用该文件的知识库文档索引会失效；只想从单个库移除用 doc delete。
• chunk delete：不可逆。
• service deploy：发布影响线上调用方；service delete 后 agent_id 不可再用（软删、幂等）。
• collection create：没有删除 API，创建数据集要慎重。
• 索引配置（embedding 模型、chunk size 等）建库后不可改，只能重建。

最佳实践

• 建服务时必须把名字写清楚：service create --name 的名称是模型判断"这个服务能查什么"的主要依据（服务描述暂未随列表接口返回）。检索服务1 这类无语义的名字会让后续检索无法路由；写成 产品文档检索、HR制度问答 这种能看出覆盖内容的名字。同时填 --description（≤1000 字符），列表接口返回该字段后即可自动生效。
• 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用，也只有 deployed 会进入模型看到的服务清单；draft 调试用 --agent-version beta。改已发布版本的配置：先改 beta 草稿（service update），验证后 service deploy 发新版本。
• 导入类命令（knowledge create、doc upload --index-id、doc status）优先带 --wait 轮询到终态，避免手工轮询；文档解析失败（如 PARSE_FAILED）会以非零退出码透传错误。
• chunk add 有 10 QPS 限流，批量脚本注意节流；响应不带 chunk id，需要 chunk list 反查。
• service list 必须带 --scene chat|search，两个场景要分别查询。