# 文档管理命令手册 文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。 > **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。 --- #### `kscli doc list` 列出知识库中的文档及其解析/索引状态。 **用法** ```bash kscli doc list --index-id [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------ | ---- | ------------------------------ | | `--index-id ` | string | 是 | 知识库 ID | | `--page-number ` | number | 否 | 页码（默认：1） | | `--page-size ` | 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` 的关系：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。 - 页大小默认 10（服务端默认），最大 100。 **示例** ```bash # 列出文档 kscli doc list --index-id idx-xxx --workspace-id ws-xxx # 每页 100 条 kscli doc list --index-id idx-xxx --page-size 100 ``` --- #### `kscli doc status` 查看知识库导入任务状态。 **用法** ```bash kscli doc status --index-id --job-id [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | --------------------------- | ------ | ---- | --------------------------------------------------- | | `--index-id ` | string | 是 | 知识库 ID | | `--job-id ` | string | 是 | 导入任务 ID（`ingestionId`，由 create/upload 返回） | | `--page-number ` | number | 否 | 页码 | | `--page-size ` | number | 否 | 每页条数 | | `--wait` | switch | 否 | 轮询直到任务到达终态 | | `--poll-interval ` | 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 可能不存在。 **示例** ```bash # 查看任务状态 kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx # 轮询等待完成，10 秒间隔 kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10 ``` --- #### `kscli doc upload` 上传本地文件或目录到数据中心，可选导入到知识库。 **用法** ```bash kscli doc upload --file [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | --------------------------- | ------ | ---- | ---------------------------------------------------------------- | | `--file ` | array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 | | `--index-id ` | string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） | | `--category-id ` | string | 否 | 目标数据中心分类（默认：工作区默认分类） | | `--tag ` | array | 否 | 文件标签（可重复），应用到每个上传的文件 | | `--wait` | switch | 否 | 轮询导入任务直到终态（需要 `--index-id`） | | `--poll-interval ` | 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 中列出。 **示例** ```bash # 上传单个文件 kscli doc upload --file ./a.md --workspace-id ws-xxx # 上传多个文件并导入到知识库，等待完成 kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait # 上传整个目录 kscli doc upload --file ./docs/ --workspace-id ws-xxx # 干跑预览（查看将上传和跳过的文件） kscli doc upload --file ./docs/ --dry-run --verbose ``` --- #### `kscli doc delete` 从知识库中删除文档及其 chunk。 **用法** ```bash kscli doc delete --index-id --doc-id [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | ----------------- | ------ | ---- | ----------------- | | `--index-id ` | string | 是 | 知识库 ID | | `--doc-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` 应从 `doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。 - 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。 - 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。 **示例** ```bash # 删除单个文档 kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx # 批量删除，跳过确认 kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes ``` --- #### `kscli doc tag` 批量更新数据中心文件的标签。 **用法** ```bash kscli doc tag --doc-id --tag [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | --------------- | ------ | ---- | ------------------------------------------------------ | | `--doc-id ` | array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） | | `--tag ` | array | 是 | 标签（可重复），应用到每个 `--doc-id` | | `--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`；不同标签集需多次执行。 **示例** ```bash # 追加标签 kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx # 覆盖标签 kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite ``` --- #### `kscli doc import-oss` 从已授权的 OSS bucket 批量导入文件到数据中心。 **用法** ```bash kscli doc import-oss --bucket --region --oss-key [flags] ``` **参数** | 参数 | 类型 | 必填 | 说明 | | -------------------- | ------ | ---- | ------------------------------------- | | `--bucket ` | string | 是 | 已授权的 OSS bucket 名称 | | `--region ` | string | 是 | OSS region ID（如 `cn-beijing`） | | `--oss-key ` | array | 是 | OSS 对象 key（可重复，最多 10 个/次） | | `--category-id ` | string | 否 | 目标数据中心分类（默认：默认分类） | | `--tag ` | 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 失效）。 **示例** ```bash # 导入单个文件 kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx # 导入多个文件并覆盖 kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite ``` --- ← [返回总览](./kscli-cli-guide.md)