bailian-kb

# 百炼知识库管理（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 去试**。 ## 前置检查 1. 安装校验：运行 `bl knowledge list --help`。若报 `Unknown command` 或 bl 未安装，执行 `npm install -g bailian-cli`（需 Node.js ≥ 18.17）；已安装但命令缺失时先 `bl update` 升级。 安装失败时把错误原样报告给用户，不要静默跳过。 2. 鉴权：需要 `DASHSCOPE_API_KEY`（环境变量，或 `bl auth login --api-key sk-xxx`，或 `bl config set --key api_key --value sk-xxx`）。 3. workspace 解析优先级：`--workspace-id` 参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > `bl config set --key workspace_id --value ws-xxx`。 ## 何时用哪个命令 | 用户意图 | 命令 | 备注 | | ---------------------------------------- | --------------------------------------------------- | -------------------------------- | | 查知识 / 问答（日常检索） | 原生工具 `kb_search` / `kb_chat` | 不走 bl | | 建库 / 查看 / 改名 / 删库 / 监控 | `bl knowledge create/list/info/update/delete/stats` | `bl knowledge create --help` | | 上传本地文档、看解析状态、删文档、打标签 | `bl knowledge doc upload/list/status/delete/tag` | `bl knowledge doc upload --help` | | 从 OSS 批量导入 | `bl knowledge doc import-oss` | Bucket 需预先授权服务角色 | | 创建 / 部署 / 调参检索（问答）服务 | `bl knowledge service create/update/deploy/…` | `bl knowledge service --help` | | 修正错误切片、屏蔽某段内容 | `bl knowledge chunk add/list/update/delete` | `bl knowledge chunk --help` | | 数据中心类目 / 文件 / 集合管理 | `bl knowledge category/file/collection …` | `bl knowledge category --help` | | CLI 配置、升级 | `bl config show/set`、`bl update` | `bl config --help` | | 部署后验证、调试草稿版服务 | `bl knowledge search/chat --agent-version beta` | `bl knowledge search --help` | ## 核心工作流：建库到可检索 ```bash bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx # 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> --yes # 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 速查（极易混淆） | 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`，两个场景要分别查询。