百炼知识库管理工具（bl，bailian-cli）用于阿里云百炼知识库的管理类操作。该工具不负责判断何时检索知识；日常查知识、问答由 kb_search（取证据）、kb_chat（成品问答）等原生工具完成，本工具只覆盖管理工作中较零散、较难自动完成的部分，包括知识库全生命周期、文档、检索服务、Chunk 和数据中心。可用检索服务的清单（含 agent_id）由插件自动注入到会话上下文，不需要为了检索先加载本工具。
检索服务清单的行为：清单由插件从百炼 API 拉取后缓存，按会话周期性刷新（约 30 分钟），只包含 deployed 状态的服务；刚用 bl 新建或部署的服务不会立刻出现在清单里，命令输出里刚拿到的 agent_id 可直接使用，不必等待刷新；服务很多时清单只列出最近修改的若干条并标明总数，查找特定服务用 bl knowledge service list --scene search --name <关键词>；清单中确实没有能回答问题的服务时，应如实告知用户。
执行入口与配置：实际操作用 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 create/list/info/update/delete/stats；上传本地文档、查看解析状态、删除文档、打标签用 bl knowledge doc upload/list/status/delete/tag；从 OSS 批量导入用 bl knowledge doc import-oss（Bucket 需预先授权服务角色）；创建、部署、调参检索或问答服务用 bl knowledge service create/update/deploy/…；修正错误切片、屏蔽某段内容用 bl knowledge chunk add/list/update/delete；数据中心类目、文件、集合管理用 bl knowledge category/file/collection …；CLI 配置、升级用 bl config show/set、bl update；部署后验证、调试草稿版服务用 bl knowledge search/chat --agent-version beta。
核心工作流（建库到可检索）：先用 bl knowledge doc upload --file ./docs/ 上传本地文件或目录，得到 fileId；再用 bl knowledge create --name my-kb --description '产品文档' --doc-id <fileId> --wait 建库并导入，得到 index-id（pipelineId）；然后用 bl knowledge service create --name my-search --scene search --index-id <index-id> 创建检索服务，得到 agent-id（draft）；接着用 bl knowledge service deploy --agent-id <agent-id> 发布服务；最后用 bl knowledge service list --scene search --status deployed 确认服务可见。部署完成后用原生工具 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 速查：index-id 来自 knowledge create 返回的 pipelineId 或 knowledge list，用于所有 knowledge/doc/chunk 命令的 --index-id；fileId 来自 doc upload 或 doc import-oss 返回，用于数据中心命令（file get/delete、knowledge create --doc-id、doc tag）；doc_id（库内文档 ID）来自 doc list 输出，用于 doc delete、chunk add/update 的 --doc-id，可能带 workspace 后缀，不等于 fileId；job-id 来自导入命令返回的 ingestionId，用于 doc status（必须同时给 --index-id 和 --job-id）；chunk id 来自 chunk list 输出的 metadata._id，用于 chunk update/delete 的 --chunk-id；agent-id 来自 service create/list，用于 service *、kb_search/kb_chat、bl knowledge search/chat。
命令参考：执行不熟悉的命令前先运行 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，两个场景要分别查询。