@@ -246,3 +246,9 @@ kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
 ---
 
 ← [返回总览](./kscli-cli-guide.md)
+
+## 音视频切片输出
+
+`chunk list` 文本在 content/text 为空时回退到 clip_description，并展示视频、音频、图片 URL、毫秒时间范围和 audio_segments。0 毫秒是有效起点；跨 clip 的音频片段不裁剪。JSON 原样保留媒体数组、历史标量与未知 metadata 字段。
+
+`chunk add` 不支持 multimedia 知识库，命令帮助明确提示；CLI 不额外查询知识库类型，服务端拒绝原样透传。不提供媒体 chunk 的新增或编辑。
@@ -266,3 +266,16 @@ kscli category delete --category-id cate-xxx --yes
 ---
 
 ← [返回总览](./kscli-cli-guide.md)
+
+## 从 collection 查历史 fileId
+
+历史 fileId 不限于 `doc import-oss` 创建的文件。先列出 collection 的分类，再逐个列出文件：
+
+```sh
+kscli category list --collection-id collection-example --output json
+kscli category list --collection-id collection-example --parent-id category-example --output json
+kscli file list --category-id category-example --output json
+kscli doc import --index-id index-example --doc-id file-example --wait
+```
+
+分类与文件列表遇到 `data.nextToken` 时，保持原过滤条件并追加 `--next-token` 继续读取；对子分类重复遍历。文件 ID 取自 `data.fileList[].fileId`，不要把分类 ID 或知识库 doc ID 当作文件 ID。`doc import` 不重复上传文件，但重新入库仍可能触发解析，真实验收仍计入一次解析预算。
@@ -1,11 +1,54 @@
 # 文档管理命令手册
 
-文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
+文档管理覆盖目录同步、文件上传、OSS 导入、已有文件入库、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
 
 > **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
 
 ---
 
+#### `kscli doc sync`
+
+将本地目录增量同步到已有知识库。`bl knowledge doc sync` 使用相同参数。
+
+```bash
+# 先预览；允许读取远端，不创建状态目录、不上传、不删除
+kscli doc sync --dir ./docs --index-id idx-xxx --dry-run
+
+# 仅新增不要求删除确认；替换或删除会返回确认要求（退出码 7）
+kscli doc sync --dir ./docs --index-id idx-xxx
+
+# 确认预览中的替换范围后执行
+kscli doc sync --dir ./docs --index-id idx-xxx --yes
+
+# 本地删文件默认保留远端；显式删除也先预览
+kscli doc sync --dir ./docs --index-id idx-xxx --delete --dry-run
+kscli doc sync --dir ./docs --index-id idx-xxx --delete --yes
+```
+
+| 参数                        | 说明                                                              |
+| --------------------------- | ----------------------------------------------------------------- |
+| `--dir <path>`              | 必填，本地文档目录；不跟随符号链接                                |
+| `--index-id <id>`           | 必填，已有文档知识库 ID                                           |
+| `--state-file <path>`       | 默认 `<dir>/.bailian/sync-state.json`，保存文件与远端文档对应关系 |
+| `--category-id <id>`        | 首次默认解析工作空间默认类目；后续使用状态中绑定的真实类目        |
+| `--sync-id <uuid>`          | 指定同步集；恢复丢失状态时需提供原 UUID                           |
+| `--delete`                  | 删除此同步集中本地已移除的索引文档                                |
+| `--poll-interval <seconds>` | 正数，默认 5 秒                                                   |
+
+每次扫描完整内容哈希，不因大小和修改时间相同而跳过校验。内容未变的已验证文档跳过上传；更新先等待新版就绪，再删除旧索引版本。重命名视为新路径添加与旧路径保留（启用 `--delete` 才删除旧路径）。不支持的格式、音视频、符号链接以及内部目录会列入跳过项；已托管路径变为不支持或不可读时，不将其视为可以删除。
+
+同步仅管理该同步集建立的文档；手工上传和其他同步集文档不会被 `--delete` 清理。源文件始终保留在数据中心。导入可能产生解析、向量化模型费用；删除文档甚至清空文档都不等于删除知识库，不会停止知识库运行时长计费。
+
+保留状态文件；CI 中将它作为持久数据保存，并为同一个同步集配置全局串行执行。本地锁不能防止不同机器同时写入。状态绑定 API 地址、工作空间、知识库、类目和同步集，不应复制到其他目标使用。
+
+状态丢失后，显式提供原 `--sync-id` 才尝试恢复当前仍存在的本地路径。只有唯一的远端路径标签匹配才恢复关联，并经确认重新上传，以重新建立内容验证；不会把远端 MD5 当成完整内容证明。远端无法还原路径的文档作为 orphan 保留，不自动删除。多个版本对应同一路径或导入结果未知时停止，需先核对资源。
+
+执行失败后保留状态文件；下一次运行先恢复未完成操作，恢复完成后重新预览剩余变更。不要删除状态或换名称来绕过未知写请求。确认之后若本地内容、状态版本或远端清单变化，执行停止，需重新预览。
+
+JSON 输出包含 `summary`、`actions`、`skipped`、`unmanaged`、`orphans`、`notices`、`stateFile`；失败时 stderr 的 `KNOWLEDGE_SYNC_INCOMPLETE` 提供最新可读 checkpoint，原错误继续输出并返回非零退出码。中途已完成的项目以 checkpoint 为准，不将部分失败报告为全部成功。
+
+---
+
 #### `kscli doc list`
 
 列出知识库中的文档及其解析/索引状态。
@@ -342,3 +385,32 @@ kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf
 ---
 
 ← [返回总览](./kscli-cli-guide.md)
+
+## 已有文件导入与音视频接入
+
+`doc upload` 从本地上传到数据中心，`doc import-oss` 从已授权 OSS 注册到数据中心；两者产生 fileId。`doc import` 把这些已有文件加入已有知识库，不重复上传。`bl knowledge doc import` 使用相同参数。
+
+```bash
+kscli doc import --index-id idx-xxx --doc-id file-xxx --wait
+kscli doc import --index-id idx-xxx --category-id cate-xxx --dry-run
+kscli 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；这些不是音视频的按秒切片参数。
+
+`doc 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 字节**，采用二进制单位。原有文档/图片的大小限制保持不变。
+
+```bash
+kscli doc upload --file ./short.mp4 --parser DOCMIND_LLM_VERSION_MEDIA --index-id idx-xxx --wait
+kscli 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。会话附件不是长期知识库入库方式。
@@ -155,3 +155,7 @@ kscli file delete --file-id file-xxx --yes
 ---
 
 ← [返回总览](./kscli-cli-guide.md)
+
+## 音视频文件
+
+`file get --file-id` 沿用现有接口查看 parser、状态和原始文件属性，JSON 保留服务端媒体字段。数据中心 fileId 可由 `file list --category-id` 分页查询，再交给 `doc import` 导入已有库。上传媒体与 parser 配置使用 [文档接入命令](doc.md#已有文件导入与音视频接入)，无需新增另一套上传协议。
@@ -125,6 +125,8 @@ kscli kb info --index-id idx-xxx --workspace-id ws-xxx
 
 创建知识库并导入数据中心文件或分类。
 
+**计费与确认**：创建成功即开始按运行时长计费，即使不检索也一样。标准版一次性 720 小时额度由多个知识库共享，新用户开通后 30 天内有效；模型调用另计，当前账户剩余额度未核实。见[计费规则](https://help.aliyun.com/zh/model-studio/billing-for-knowledge-base)。先用 `--dry-run` 预览；实际创建未带 `--yes` 时返回退出码 7（`requires_confirmation`），不会创建资源。确认本次操作及范围后才添加 `--yes`。
+
 **用法**
 
 ```bash
@@ -169,10 +171,12 @@ json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和
 
 **注意事项**
 
-- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
+- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。音视频类型见文末 [音视频知识库](#音视频知识库)。
 - 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
 - 使用 `doc status` 或 `--wait` 跟踪导入进度。
-- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
+- 创建响应返回后立即向 stderr 报告知识库 ID、工作空间与持续计费提醒，quiet 模式也保留；JSON 结果保留 API 响应并追加资源和提醒信息。
+- 当前产品注册了删除命令时，资源中的 `cleanup.command` 给出真实 `bin`、`path` 和 `args`；text 模式显示可复制的指令。指令不自动添加 `--yes`，不存在唯一删除路径时不猜测路径。
+- 如果后续等待失败，命令返回非零退出码，知识库仍可能已创建并持续计费。根据已输出 ID 核对资源，不要盲目重复创建。确认不再需要后，使用 `kscli kb delete --index-id <index-id> --workspace-id <workspace-id>` 清理；确认删除范围后才添加 `--yes`。仅删除文档或检索服务不能停止知识库规格计费。
 
 **示例**
 
@@ -340,3 +344,17 @@ kscli kb stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
 ---
 
 ← [返回总览](./kscli-cli-guide.md)
+
+## 音视频知识库
+
+`kb create` 支持 `--knowledge-type document|multimedia`、`--knowledge-scene` 和 `--multimodal-embedding-model`。音视频类型固定使用 `basic_multimedia_qa`；未传 scene 时自动填充，显式冲突时本地拒绝。
+
+```sh
+kscli kb create --name media-demo --description "音视频资料" --doc-id file-example --knowledge-type multimedia
+```
+
+音视频请求默认发送 `embeddingModelName=qwen3-vl-embedding`、`rerankModelName=qwen3-vl-rerank`、`rerankMode=similar`，与管控台切换逻辑及现有音视频库的只读配置一致。音视频场景的 `--multimodal-embedding-model` 是 `--embedding-model` 的别名，两者互斥，均映射到 `embeddingModelName`，不能误用图片建库的 `multimodalEmbeddingModelName`。视觉理解文档场景 `visual_perception_qa` 同样使用 VL embedding，但不默认加入 rerank。
+
+普通文档未使用新参数时仍为 `text-embedding-v4`。显式模型仍由服务端校验其允许列表；CLI 不把当前观察到的模型名称硬编码成永久白名单。只读核对不代表已新建媒体库进行解析验收。
+
+`kb list` 文本增加类型，`kb info` 文本展示 knowledgeType、knowledgeScene、multimodalEmbeddingModelName。JSON 保留服务端对象及未知字段。列表接口缺少这三个字段按后端 bug 处理；null/缺失不代表普通文档库，CLI 不发额外探测请求、不推断或写回，也不提供 multimediaVersion 参数。