dingtalk-workspace-cli/skills/multi/dingtalk-doc/references/doc/doc-file-ops.md

doc 文件操作（upload / download / copy / move / rename / delete + folder create）

前置条件（MUST READ）： 执行本命令前，必须先用 Read 工具读取以下文件：

1. ../doc.md — 命令路由 + 场景索引 + 意图判断 + 工作流

---

doc upload（上传文件到钉钉文档/知识库）

Usage:
  dws doc upload [flags]
Example:
  dws doc upload --file ./report.pdf
  dws doc upload --file ./slides.pptx --name "Q1汇报.pptx" --folder <DOC_FOLDER_NODE_ID>
  dws doc upload --file ./data.xlsx --workspace <WS_ID> --convert
Flags:
      --file string        本地文件路径 (必填)
      --name string        文件显示名称 (默认使用文件名)
      --folder string      目标文档文件夹 nodeId 或 alidocs 文件夹 URL；不要传 drive dentryId/parent-id 这类纯数字 ID
      --workspace string   目标知识库 ID
      --convert            是否转换为钉钉在线文档

关键说明

• upload 是三步自动完成的流程（获取凭证 → OSS 上传 → 提交入库），无需手动分步操作。
• 支持上传任意类型文件（PDF、Office、图片等）到钉钉文档空间或知识库。
• --convert 可将 Office 文件转换为钉钉在线文档。
• doc upload vs drive upload：用户提到「知识库 / 文档空间 / workspace」→ doc upload；提到「钉盘 / 网盘 / 我的文件」→ drive upload；未明确目标时默认 drive upload。
• 与 ./doc-media.md media insert 的区别：upload 上传到文档空间作为独立文件；media insert 作为附件块插入到文档正文中。

---

doc download（下载文件到本地）

路由前置判断：用户说「下载 / 导出」时必须先用 ./doc-info.md info --node <ID> --format json 查 contentType：

• contentType 为 ALIDOC（在线文档）→ 走 ./doc-export.md export
• contentType 为 DOCUMENT/IMAGE/VIDEO 等（已有文件）→ 走本命令 download

Usage:
  dws doc download [flags]
Example:
  dws doc download --node <NODE_ID>
  dws doc download --node <NODE_ID> --output ./report.pdf
  dws doc download --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --output ~/downloads/
Flags:
      --node string     文件节点 ID 或 URL (必填)
      --output string   本地保存路径 (文件路径或目录，必填)

关键说明

• download 是两步自动完成的流程（获取下载链接 → HTTP GET 下载），支持自动推断文件名；--output 可指定文件路径或目录。
• 严禁将「导出文档」直接路由到 download——download 只能下载已有文件（原样下载），export 是将在线文档格式转换后导出为 docx。

---

doc copy（复制文档/文件）

Usage:
  dws doc copy [flags]
Example:
  dws doc copy --node <DOC_ID> --folder <TARGET_DOC_FOLDER_NODE_ID>
  dws doc copy --node <DOC_ID> --workspace <TARGET_WS_ID>
  dws doc copy --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --folder <DOC_FOLDER_NODE_ID>
Flags:
      --node string        文档/文件 ID 或 URL (必填)
      --folder string      目标文档文件夹 nodeId 或 alidocs 文件夹 URL；不要传 drive dentryId/parent-id 这类纯数字 ID
      --workspace string   目标知识库 ID 或 URL (不传 --folder 时复制到该知识库根目录)

关键说明

• 需要对源文档有「阅读」权限，且对目标文件夹有「编辑」权限。
• copy 是异步任务，若任务未完成则不会返回新文档 ID；如需获取可稍后通过 ./doc-list.md 查询目标文件夹。

---

doc move（移动文档/文件）

Usage:
  dws doc move [flags]
Example:
  dws doc move --node <DOC_ID> --folder <TARGET_DOC_FOLDER_NODE_ID>
  dws doc move --node <DOC_ID> --workspace <TARGET_WS_ID>
  dws doc move --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --folder <DOC_FOLDER_NODE_ID>
Flags:
      --node string        文档/文件 ID 或 URL (必填)
      --folder string      目标文档文件夹 nodeId 或 alidocs 文件夹 URL；不要传 drive dentryId/parent-id 这类纯数字 ID
      --workspace string   目标知识库 ID 或 URL (不传 --folder 时移动到该知识库根目录)

关键说明

• 需要对源文档有「管理」权限，且对目标文件夹有「编辑」权限；移动后原位置的文档将不再存在。

---

doc rename（重命名文档/文件）

Usage:
  dws doc rename [flags]
Example:
  dws doc rename --node <DOC_ID> --name "新名称"
  dws doc rename --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --name "项目周报 v2"
Flags:
      --node string   文档/文件 ID 或 URL (必填)
      --name string   新名称 (必填)

关键说明

• 需要对文档有「编辑」权限。
• 只要意图是修改文档在列表和链接中展示的名称，统一路由到本命令；不要走 drive、doc update 或重新 doc create。
• 只有用户明确说「正文里的标题/章节标题/段落标题/H1 标题」时，才走 ./doc-block.md block update。

---

doc delete（删除到回收站）

CAUTION: 不可逆操作 — 执行前必须向用户确认。

Usage:
  dws doc delete [flags]
Example:
  dws doc delete --node <DOC_ID> --format json    # 查询 nodeId: dws doc search --query "..." 或 dws doc list
Flags:
      --node string   文档/文件 ID 或 URL (必填)

权限要求: 对文档有「管理」权限。

正确流程：1.向用户展示「即将删除「文档名」到回收站」 → 2.等用户确认 → 3.执行 dws doc delete --node <ID> --yes。

---

doc folder create（创建文件夹）

Usage:
  dws doc folder create [flags]
Example:
  dws doc folder create --name "项目资料"
  dws doc folder create --name "子文件夹" --folder <PARENT_DOC_FOLDER_NODE_ID>
Flags:
      --name string        文件夹名称 (必填)
      --folder string      父文档文件夹 nodeId 或 alidocs 文件夹 URL；不要传 drive dentryId/parent-id 这类纯数字 ID
      --workspace string   目标知识库 ID

上下文传递

操作	从返回中提取	用于
upload	nodeId / URL	上传后文件的访问链接；后续 --node 入参
download	本地文件路径	下载后的文件保存位置
copy	nodeId / URL（异步，不保证返回）	异步任务，未完成时不返回新文档 ID；可用 ./doc-list.md 在目标文件夹查询
folder create	nodeId	./doc-create.md / list / upload / copy / move 的 --folder

常用模板

# ── upload ──
# 上传到「我的文档」根目录
dws doc upload --file ./report.pdf

# 上传到指定文件夹
dws doc upload --file ./slides.pptx --name "Q1汇报.pptx" --folder <DOC_FOLDER_NODE_ID>

# 上传到知识库并转换为在线文档
dws doc upload --file ./data.xlsx --workspace <WS_ID> --convert

# ── download（仅限非 ALIDOC 文件）──
# 自动推断文件名，下到目录
dws doc download --node <NODE_ID> --output ~/downloads/

# 指定文件路径
dws doc download --node <NODE_ID> --output ./report.pdf

# ── copy ──
# 复制到指定文件夹（异步）
dws doc copy --node <DOC_ID_OR_URL> --folder <TARGET_DOC_FOLDER_NODE_ID> --format json

# 复制到目标知识库根目录
dws doc copy --node <DOC_ID_OR_URL> --workspace <TARGET_WS_ID> --format json

# ── move ──
# 移动到指定文件夹
dws doc move --node <DOC_ID_OR_URL> --folder <TARGET_DOC_FOLDER_NODE_ID> --format json

# 移动到知识库根目录
dws doc move --node <DOC_ID_OR_URL> --workspace <TARGET_WS_ID> --format json

# ── rename ──
dws doc rename --node <DOC_ID_OR_URL> --name "新名称" --format json

# ── delete（用户确认后才加 --yes）──
dws doc delete --node <DOC_ID_OR_URL> --yes --format json

# ── folder create ──
# 在「我的文档」根目录创建
dws doc folder create --name "项目资料" --format json

# 在指定父文件夹下创建
dws doc folder create --name "子文件夹" --folder <PARENT_DOC_FOLDER_NODE_ID> --format json

# 在知识库下创建
dws doc folder create --name "项目资料" --workspace <WS_ID> --format json

参考

• ../doc.md §意图判断（如何路由到本命令族）
• ./doc-info.md（前置：判断 contentType 决定 download / export）
• ./doc-export.md（在线文档格式转换导出 docx）
• ./doc-media.md（文件作为附件块插入文档正文，与 upload 区分）
• ./doc-search.md / ./doc-list.md（拿 nodeId 的入口）