文档管理覆盖目录同步、文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
通用约定（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 总览文档。
将本地目录增量同步到已有知识库；kscli 的对应路径是 kscli doc sync。
# 先预览；允许读取远端，不创建状态目录、不上传、不删除
bl knowledge doc sync --dir ./docs --index-id idx-xxx --dry-run
# 仅新增不要求删除确认；替换或删除会返回确认要求（退出码 7）
bl knowledge doc sync --dir ./docs --index-id idx-xxx
# 确认预览中的替换范围后执行
bl knowledge doc sync --dir ./docs --index-id idx-xxx --yes
# 本地删文件默认保留远端；显式删除也先预览
bl knowledge doc sync --dir ./docs --index-id idx-xxx --delete --dry-run
bl knowledge doc sync --dir ./docs --index-id idx-xxx --delete --yes| 参数 | 说明 |
|---|---|
--dir <path> |
必填，本地文档目录；不跟随符号链接 |
--index-id <id> |
必填，已有文档知识库 ID |
--state-file <path> |
显式指定状态路径；默认 <dir>/.bailian/sync/<key>.json，按知识库 ID 自动隔离 |
--category-id <id> |
首次默认解析工作空间默认类目；后续使用状态中绑定的真实类目 |
--sync-id <uuid> |
指定同步集；恢复丢失状态时需提供原 UUID |
--delete |
删除此同步集中本地已移除的索引文档 |
--poll-interval <seconds> |
正数，默认 5 秒 |
每次扫描完整内容哈希，不因大小和修改时间相同而跳过校验。内容未变的已验证文档跳过上传；更新先等待新版就绪，再删除旧索引版本。重命名视为新路径添加与旧路径保留（启用 --delete 才删除旧路径）。不支持的格式、音视频、符号链接以及内部目录会列入跳过项；已托管路径变为不支持或不可读时，不将其视为可以删除。
同步仅管理该同步集建立的文档；手工上传和其他同步集文档不会被 --delete 清理。源文件始终保留在数据中心。导入可能产生解析、向量化模型费用；删除文档甚至清空文档都不等于删除知识库，不会停止知识库运行时长计费。
默认文件名中的 key 是 [indexId] 的 JSON 表示的 SHA-256 摘要，只由知识库 ID 决定。同一文档目录切换 --index-id 时自动使用独立状态，切回原 ID 时继续原同步集，无需手动指定 --state-file。实际路径显示在预览和执行结果中。当前测试阶段不读取或迁移旧默认路径 <dir>/.bailian/sync-state.json。
保留状态文件；CI 中将它作为持久数据保存，并为同一个同步集配置全局串行执行。本地锁不能防止不同机器同时写入。路径按知识库 ID 选择，记录内容仍校验 API 地址、工作空间、知识库、类目和同步集，不应复制到其他目标使用。显式 --state-file 优先于自动路径，并保留这些校验。
状态丢失后，显式提供原 --sync-id 才尝试恢复当前仍存在的本地路径。只有唯一的远端路径标签匹配才恢复关联，并经确认重新上传，以重新建立内容验证；不会把远端 MD5 当成完整内容证明。远端无法还原路径的文档作为 orphan 保留，不自动删除。多个版本对应同一路径或导入结果未知时停止，需先核对资源。
执行失败后保留状态文件；下一次运行先恢复未完成操作，恢复完成后重新预览剩余变更。不要删除状态或换名称来绕过未知写请求。确认之后若本地内容、状态版本或远端清单变化，执行停止，需重新预览。
JSON 输出包含 summary、actions、skipped、unmanaged、orphans、notices、stateFile；失败时 stderr 的 KNOWLEDGE_SYNC_INCOMPLETE 提供最新可读 checkpoint，原错误继续输出并返回非零退出码。中途已完成的项目以 checkpoint 为准，不将部分失败报告为全部成功。
列出知识库中的文档及其解析/索引状态。
用法
bl knowledge doc list --index-id <id> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--index-id <id> |
string | 是 | 知识库 ID |
--page-number <n> |
number | 否 | 页码（默认：1） |
--page-size <n> |
number | 否 | 每页条数（默认：10，最大 100） |
参数约束
--page-size范围 1-100
输出
text 模式：每行一个文档，FAILED 状态的文档红色高亮。
doc-xxx COMPLETED intro.md md 1024
total: 1
quiet 模式：每行一个 doc_id。
json 模式：返回 API 原始响应。
注意事项
doc_id与file_id的关系：通过knowledge create --doc-id导入的文档，doc_id等于fileId；通过knowledge doc upload --index-id导入的，doc_id可能包含 workspace 后缀。- 页大小默认 10（服务端默认），最大 100。
示例
# 列出文档
bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
# 每页 100 条
bl knowledge doc list --index-id idx-xxx --page-size 100查看知识库导入任务状态。
用法
bl knowledge doc status --index-id <id> --job-id <id> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--index-id <id> |
string | 是 | 知识库 ID |
--job-id <id> |
string | 是 | 导入任务 ID（ingestionId，由 create/upload 返回） |
--page-number <n> |
number | 否 | 页码 |
--page-size <n> |
number | 否 | 每页条数 |
--wait |
switch | 否 | 轮询直到任务到达终态 |
--poll-interval <seconds> |
number | 否 | 轮询间隔秒数（默认：5） |
输出
text 模式：
status: COMPLETED
doc-xxx COMPLETED intro.md
quiet 模式：输出任务状态（PENDING/RUNNING/COMPLETED）。
json 模式：返回 API 原始响应，data.rows[] 包含每个文档的状态。
注意事项
--index-id和--job-id服务端均要求必传，只传一个会返回SystemError。- 整体任务状态为
PENDING/RUNNING/COMPLETED（无FAILED值）。 - 单个文档可能解析失败（如
PARSE_FAILED），此时 CLI 以非零退出码报错，服务端消息原样透传。 - 如果服务端对空闲知识库返回
SystemError，说明该 job 可能不存在。
示例
# 查看任务状态
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
# 轮询等待完成，10 秒间隔
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10上传本地文件或目录到数据中心，可选导入到知识库。
用法
bl knowledge doc upload --file <path> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--file <path> |
array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
--index-id <id> |
string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） |
--category-id <id> |
string | 否 | 目标数据中心分类（默认：工作区默认分类） |
--tag <text> |
array | 否 | 文件标签（可重复），应用到每个上传的文件 |
--wait |
switch | 否 | 轮询导入任务直到终态（需要 --index-id） |
--poll-interval <seconds> |
number | 否 | 轮询间隔秒数（默认：5） |
参数约束
--wait要求同时指定--index-id
输出
text 模式：
intro.md file-xxx registered
job: job-xxx
status: COMPLETED
Uploaded 1 file.
quiet 模式：每行一个 fileId。
json 模式：返回自定义结构，包含 files（路径和 fileId）、skipped、index_id、ingestion_id、final_status。
注意事项
- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。
- 目录递归扫描，
node_modules、.git等自动跳过。 - 多文件按顺序处理（无并发），避免 OSS 限流。
- 支持的文件格式：
.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif - 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。
示例
# 上传单个文件
bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
# 上传多个文件并导入到知识库，等待完成
bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
# 上传整个目录
bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
# 干跑预览（查看将上传和跳过的文件）
bl knowledge doc upload --file ./docs/ --dry-run --verbose从知识库中删除文档及其 chunk。
用法
bl knowledge doc delete --index-id <id> --doc-id <id> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--index-id <id> |
string | 是 | 知识库 ID |
--doc-id <id> |
array | 是 | 文档 ID（可重复） |
--yes |
switch | 否 | 显式确认高风险操作 |
输出
text 模式：
deleted: 2 document(s)
doc-a
doc-b
quiet 模式：每行一个已删除的 doc_id。
json 模式：返回 API 原始响应，data.deleted[] 为实际删除的 ID 列表。
注意事项
- 只从知识库索引中移除文档，数据中心源文件不受影响（用
file delete删除源文件）。 doc_id应从knowledge doc list --quiet获取，而非doc upload返回的fileId。- 删除是异步的：服务端立即返回 Success，但
doc list中可能仍显示该文档（约 30 秒后传播完成）。 - 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
示例
# 删除单个文档
bl knowledge doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
# 用户明确确认后批量删除
bl knowledge doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes批量更新数据中心文件的标签。
用法
bl knowledge doc tag --doc-id <id> --tag <text> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--doc-id <id> |
array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） |
--tag <text> |
array | 是 | 标签（可重复），应用到每个 --doc-id |
--mode <mode> |
string | 否 | 更新模式：append（默认，追加）或 overwrite（覆盖） |
参数约束
--doc-id最多 20 个/次--tag最多 100 个- 每个标签最多 32 字符
- 标签总长度最多 700 字符
--mode只能是append或overwrite
输出
text 模式：
tagged: 2 file(s) with [project-a, draft]
quiet 模式：无输出。
json 模式：返回 API 原始响应。
注意事项
- 同一组标签应用到所有
--doc-id；不同标签集需多次执行。
示例
# 追加标签
bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
# 覆盖标签
bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite从已授权的 OSS bucket 批量导入文件到数据中心。
用法
bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--bucket <name> |
string | 是 | 已授权的 OSS bucket 名称 |
--region <id> |
string | 是 | OSS region ID（如 cn-beijing） |
--oss-key <key> |
array | 是 | OSS 对象 key（可重复，最多 10 个/次） |
--category-id <id> |
string | 否 | 目标数据中心分类（默认：默认分类） |
--tag <text> |
array | 否 | 文件标签（可重复，最多 10 个） |
--overwrite |
switch | 否 | 覆盖之前从相同 OSS key 导入的文件 |
参数约束
--oss-key最多 10 个/次--tag最多 10 个
输出
text 模式：
imported: 2 file(s)
file-a SUCCESS docs/a.pdf
file-b SUCCESS docs/b.docx
quiet 模式：每行一个 fileId。
json 模式：返回 API 原始响应，data.addFileResultList[] 包含每个文件的 fileId、status 和 ossKey。
注意事项
- bucket 必须事先授权给平台服务角色（RAM 中的
AliyunServiceRoleForBailian）。 - 文件名取自 OSS key 的 basename。
--overwrite会替换之前导入的文件并生成新的 fileId（旧 fileId 失效）。
示例
# 导入单个文件
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
# 导入多个文件并覆盖
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite← 返回总览
doc upload 从本地上传到数据中心，doc import-oss 从已授权 OSS 注册到数据中心；两者产生 fileId。新增 doc import 把这些已有文件加入已有知识库，不重复上传。kscli 使用相同参数，省略 knowledge 前缀。
bl knowledge doc import --index-id idx-xxx --doc-id file-xxx --wait
bl knowledge doc import --index-id idx-xxx --category-id cate-xxx --dry-run
bl knowledge doc list --index-id idx-xxx --details --page-number 2 --page-size 10--doc-id 与 --category-id 可重复但互斥，必须选一种。--wait 与 --poll-interval 控制等待；返回 ingestionId。等待会汇总任务所有页的文件状态，失败文件不会因不在第一页而漏掉。超时后用原 ingestionId 继续查询，不必重新导入。
普通文档可传 --chunk-mode h1|h2|h3|h4|h5|length|page|regex、--chunk-size、--overlap-size、--separator、--enable-headers true|false。length 需要 chunk-size，regex 需要 separator；这些不是音视频的按秒切片参数。
| 参数 | 类型 | 说明 |
|---|---|---|
--index-id |
string | 必填，目标已有知识库 ID。 |
--doc-id |
array | 数据中心 fileId，可重复；与 category-id 二选一，不是本地路径。 |
--category-id |
array | 数据中心分类 ID，可重复；与 doc-id 互斥。 |
--workspace-id |
string | 目标工作空间；也可使用已配置值。 |
--wait |
switch | 等待导入完成；不传时提交任务后返回。 |
--poll-interval |
number | 轮询间隔秒数，默认 5，必须为正数。 |
--chunk-mode |
string | h1/h2/h3/h4/h5/length/page/regex，文档切片模式。 |
--chunk-size |
number | 1–6000 的整数；length 模式必填。 |
--overlap-size |
number | 0–1024 的整数。 |
--separator |
string | regex 模式必填的分隔表达式。 |
--enable-headers |
boolean | 显式传 true 或 false，控制标题提取。 |
--dry-run |
switch | 预览请求，不执行导入。 |
导入复用已有 fileId，不重新上传文件或创建知识库。任务返回 ingestionId；需要实际完成状态时使用 --wait。已有文件的类型和导入数量由服务端校验，不能用分类个数代替文件数。文档切片参数不是音视频按秒切片参数。
- 已上传单个文件：使用 --doc-id fileId，向已有知识库发起导入。
- 已上传多个文件：重复传 --doc-id；不要传逗号拼接的 ID 字符串。
- 按分类导入：使用 --category-id，可重复；不能与 --doc-id 混用。
- 两种来源均未提供或同时提供：本地校验失败，不发起导入。
- 等待超时或任务部分失败：保留返回的 ingestionId，通过 doc status 核对；不要直接重复提交。等待会检查所有页的文件状态，不把部分失败报告为全部成功。
bl knowledge doc import --index-id idx-xxx --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
kscli doc import --index-id idx-xxx --category-id cate-xxx --workspace-id ws-xxx --dry-run
bl knowledge doc import --index-id idx-xxx --doc-id file-xxx --chunk-mode length --chunk-size 600 --overlap-size 100 --enable-headers true --dry-rundoc list --details 调用文件详情列表接口，文本显示 chunkSize、overlapSize、separator、chunkMode、enableHeaders；JSON 保留原始响应。详情接口每页最多 10 条，默认普通列表仍为最多 100 条。
音视频格式：aac、amr、flac、flv、m4a、mp3、mpeg、ogg、opus、wav、webm、wma、mp4、mkv、avi、mov、wmv。后缀不区分大小写，目录扫描包含这些格式。单文件本地上限 2 GiB = 2,147,483,648 字节，用户已确认采用二进制单位。原有文档/图片的大小限制保持不变。
bl knowledge doc upload --file ./short.mp4 --parser DOCMIND_LLM_VERSION_MEDIA --index-id idx-xxx --wait
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key samples/short.mp4 --parser DOCMIND_LLM_VERSION_MEDIA两个接入命令均支持 --parser-config-file <JSON对象文件>，保留未知配置键；OSS 参数应用到本批每个 fileDetails 元素。未指定 parser 时保持原有默认行为。上传使用流式 MD5 和流式 PUT，不把整个媒体加载进内存。
带 --index-id 时，一次最多接入 50 个已知本地媒体文件，超限在上传前拒绝，不自动拆批。历史 fileId 和类目的类型/数量由服务端验证；类目个数不等于文件数。OSS 注册仍最多 10 个对象，与知识库导入上限不同。
临时问答附件使用 doc upload --category-type SESSION_FILE，租约和注册都传同一类型；不能同时指定 index-id 或自定义 parser/config。会话附件不是长期知识库入库方式。