Skip to main content

文档管理命令

kscli doc 命令组，上传文件、OSS 导入、解析状态跟踪与标签管理

文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签维护。文档导入知识库后自动解析为切片。本组共 6 个命令。 鉴权、业务空间 ID、全局参数、输出格式、二次确认和干跑模式等通用约定见 CLI 概述。以下示例默认已通过配置文件设置业务空间 ID。

kscli doc list

列出知识库中的文档及其解析状态。 
kscli doc list --index-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--page-number <n>number否页码，默认 1
--page-size <n>number否每页条数，默认 10，范围 1–100
输出 text 模式每行一个文档，FAILED 状态的文档以红色高亮： 
doc-xxx  COMPLETED  intro.md  md  1024
total: 1
quiet 模式每行输出一个 doc_id。json 模式返回完整结果。
文档在知识库中的 doc_id 与数据中心的文件 ID 不一定相同，取决于导入方式。对知识库文档的后续操作（如 doc delete、chunk update）请以本命令输出的 doc_id 为准。
示例 
# 列出文档
kscli doc list --index-id idx-xxx

# 每页 100 条
kscli doc list --index-id idx-xxx --page-size 100

kscli doc status

查看知识库导入任务的执行状态。 
kscli doc status --index-id <id> --job-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--job-id <id>string是导入任务 ID，由 kb create 或 doc upload 返回
--page-number <n>number否页码，默认 1
--page-size <n>number否每页条数
--waitswitch否轮询直到任务到达终态
--poll-interval <seconds>number否轮询间隔秒数，默认 5
输出 
status: COMPLETED
  doc-xxx  COMPLETED  intro.md
quiet 模式输出任务整体状态。json 模式返回完整结果，包含每个文档的状态。 注意事项
  • 任务整体状态为 PENDING、RUNNING 或 COMPLETED。
  • 单个文档可能解析失败（如 PARSE_FAILED），此时命令以非零退出码结束并展示服务端错误信息。
  • 服务端返回 SystemError 通常说明该任务 ID 不存在，请从 doc upload 或 kb create 的返回结果中确认。
示例 
# 查询一次
kscli doc status --index-id idx-xxx --job-id job-xxx

# 轮询等待完成，间隔 10 秒
kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10

kscli doc upload

上传本地文件或目录到数据中心，可选择同时导入知识库。 
kscli doc upload --file <path> [flags]
参数
参数类型必填说明
--file <path>array是本地文件或目录路径，可重复传入。目录递归扫描，不支持的格式自动跳过
--index-id <id>string否上传后导入此知识库，所有文件合并为一个导入任务
--category-id <id>string否目标数据中心分类，默认为业务空间的默认分类
--tag <text>array否文件标签，可重复传入，应用到每个上传的文件
--waitswitch否轮询导入任务直到终态，需同时指定 --index-id
--poll-interval <seconds>number否轮询间隔秒数，默认 5
输出 
intro.md  file-xxx  registered
job: job-xxx
status: COMPLETED

Uploaded 1 file.
quiet 模式每行输出一个文件 ID。json 模式返回 files（路径与文件 ID）、skipped、index_id、ingestion_id、final_status 字段。 支持的文件格式 .pdf、.doc、.docx、.ppt、.pptx、.xls、.xlsx、.csv、.md、.txt、.html、.png、.jpg、.jpeg、.bmp、.gif 注意事项
  • 目录递归扫描时，node_modules、.git 等目录自动跳过。
  • 多文件按顺序逐个上传。部分文件上传失败时，已成功上传的文件 ID 会在错误提示中列出，便于续传或清理。
  • 上传大批量文件前，建议先用 --dry-run --verbose 确认将上传和跳过的文件清单。
示例 
# 上传单个文件
kscli doc upload --file ./a.md

# 上传多个文件并导入知识库，等待解析完成
kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait

# 上传整个目录
kscli doc upload --file ./docs/

# 干跑预览
kscli doc upload --file ./docs/ --dry-run --verbose

kscli doc delete

从知识库中删除文档及其切片。 
kscli doc delete --index-id <id> --doc-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--doc-id <id>array是文档 ID，可重复传入
--yesswitch否跳过确认提示
输出 
deleted: 2 document(s)
  doc-a
  doc-b
quiet 模式每行输出一个已删除的 doc_id。json 模式返回实际删除的 ID 列表。 注意事项
  • 只从知识库索引中移除文档，数据中心的源文件保留。如需删除源文件，使用 kscli file delete。
  • doc_id 应从 kscli doc list --quiet 获取，而不是 doc upload 返回的文件 ID。
  • 删除是异步执行的：命令立即返回成功，但 doc list 中可能仍短暂显示该文档，约 30 秒后生效。
  • 输出的是实际删除的 ID 列表，数量可能与请求不一致，差异会在 stderr 中警告。
示例 
# 删除单个文档
kscli doc delete --index-id idx-xxx --doc-id doc-xxx

# 批量删除并跳过确认
kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes

kscli doc tag

批量更新数据中心文件的标签。 
kscli 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 字符
输出 
tagged: 2 file(s) with [project-a, draft]
quiet 模式无输出。json 模式返回完整结果。
--mode overwrite 会用本次传入的标签替换文件上的全部现有标签，被替换掉的标签无法恢复。仅在确认要清空原标签时使用，否则用默认的 append。
同一组标签会应用到所有 --doc-id。需要给不同文件打不同标签时，分多次执行。 示例 
# 追加标签
kscli doc tag --doc-id file-xxx --tag project-a --tag draft

# 覆盖标签
kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite

kscli doc import-oss

从已授权的 OSS bucket 批量导入文件到数据中心。 
kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
参数
参数类型必填说明
--bucket <name>string是已授权的 OSS bucket 名称
--region <id>string是OSS 地域 ID，如 cn-beijing
--oss-key <key>array是OSS 对象 key，可重复传入，每次最多 10 个
--category-id <id>string否目标数据中心分类，默认为默认分类
--tag <text>array否文件标签，可重复传入，最多 10 个
--overwriteswitch否覆盖之前从相同 OSS key 导入的文件
输出 
imported: 2 file(s)
  file-a  SUCCESS  docs/a.pdf
  file-b  SUCCESS  docs/b.docx
quiet 模式每行输出一个文件 ID。json 模式返回每个文件的文件 ID、状态和 OSS key。 注意事项
  • bucket 必须事先授权给平台服务。在 RAM 控制台确认 AliyunServiceRoleForBailian 服务角色已对该 bucket 正确授权，否则导入返回权限错误。
  • 导入后的文件名取自 OSS key 的最后一段。
  • --overwrite 会替换之前导入的文件并生成新的文件 ID，旧文件 ID 随之失效。如果有知识库或脚本引用了旧 ID，需要同步更新。
示例 
# 导入单个文件
kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf

# 导入多个文件并覆盖同 key 的旧文件
kscli doc import-oss --bucket my-bucket --region cn-beijing \
  --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
文档管理命令 - Knowledge Studio