Files

T

Aemeathand张卓澎 657d2c25e3 feat: sync open product command capabilities (#608 )

Co-authored-by: 张卓澎 <zhuopeng.zzp@alibaba-inc.com>

2026-07-13 17:21:47 +08:00

53 KiB

Raw Permalink Blame History

文档 (doc) 命令参考

查询命令帮助

当你不确定某个命令的具体参数、格式或可选项时，优先执行 --help 查询，不要猜测参数名或凭记忆编造。

# 查看 doc 下所有子命令
dws doc --help

# 查看具体命令的完整参数说明
dws doc read --help
dws doc create --help
dws doc block insert --help

# 查看子命令组下的所有命令
dws doc block --help
dws doc permission --help

规则：

参数名不确定时 → 先 --help，再调用
报错 "unknown flag" 时 → --help 确认正确的 flag 名称
不确定某个功能是否存在时 → dws doc --help 查看命令列表

命令总览

搜索 / 遍历文件（已迁移，不再是 doc 子命令）

弃用提示：dws doc search 和 dws doc list 已迁移到 drive / wiki。这两条虽仍能跑，但每次都会打印弃用警告，请改用下面的命令，命令详情见 dingtalk-drive skill。

旧命令（弃用）	改用	场景
`dws doc search --query "<关键词>"`	`dws drive search --query "<关键词>"`	全局搜文档/文件（跨钉盘+文档空间聚合）
`dws doc search --workspace-ids <id>`	`dws wiki node search --workspace <id> --query "<关键词>"`	指定知识库内搜索
`dws doc list`	`dws drive list`	遍历「我的文档」/钉盘根目录
`dws doc list --folder <id>`	`dws drive list --folder <id>`	遍历指定文件夹
`dws doc list --workspace <id>`	`dws drive list --workspace <id>` 或 `dws wiki node list --workspace <id>`	遍历知识库

拿到 nodeId 后，doc read / doc info / doc update / doc block 等内容级命令照常用。

获取文档元信息

Usage:
  dws doc info [flags]
Example:
  dws doc info --node <DOC_ID>
  dws doc info --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>"
  dws doc info --node "https://alidocs.dingtalk.com/document/edit?dentryKey=<DENTRY_KEY>"
  dws doc info --node "https://alidocs.dingtalk.com/document/preview?dentryKey=<DENTRY_KEY>"
Flags:
      --node string   文档 ID 或 URL (必填)

读取文档内容

Usage:
  dws doc read [flags]
Example:
  dws doc read --node <DOC_ID>
  dws doc read --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>"
  dws doc read --node "https://alidocs.dingtalk.com/document/edit?dentryKey=<DENTRY_KEY>"
  dws doc read --node "https://alidocs.dingtalk.com/document/preview?dentryKey=<DENTRY_KEY>"
Flags:
      --node string   文档 ID 或 URL (必填)

创建文档

Usage:
  dws doc create [flags]
Example:
  dws doc create --name "项目周报"
  dws doc create --name "Q1 总结" --content "# Q1 总结" --folder <FOLDER_ID>
  dws doc create --name "知识库文档" --workspace <WS_ID>
Flags:
      --name string           文档名称 (必填)
      --folder string         父文件夹 nodeId / URL
      --workspace string      Workspace ID
      --content string        初始 Markdown 内容
      --content-file string   从文件读取初始 Markdown

创建其他类型文件 (表格/脑图/白板/多维表/画板/文件夹)

弃用提示：dws doc file create --type 已弃用，执行时会打印 deprecated, use 'dws wiki node create --type <type>'。创建各类型文件节点改用 dws wiki node create（与 intent-guide 一致）；创建普通文件夹用 dws drive mkdir。

Usage:
  dws wiki node create [flags]
Example:
  dws wiki node create --workspace <WS_ID> --name "数据统计" --type axls
  dws wiki node create --workspace <WS_ID> --name "思维导图" --type amind
  dws wiki node create --workspace <WS_ID> --name "方案目录" --type folder --folder <PARENT_NODE_ID>
Flags:
      --workspace string   目标知识库 ID (必填 — wiki node create 不支持不带 workspace 创建)
      --name string        文件名称 (必填)
      --type string        文件类型: adoc=文档, axls=表格, appt=演示, adraw=白板, amind=脑图, able=多维表, folder=文件夹
      --folder string      父节点 ID (选填)

说明：wiki node create 必须带 --workspace（知识库上下文），不能像旧 doc file create 那样在「我的文档」个人空间直接建。要在个人空间/钉盘建普通文件夹，用 dws drive mkdir --name "<名称>"（见 dingtalk-drive skill）。

更新文档内容

Usage:
  dws doc update [flags]
Example:
  dws doc update --node <DOC_ID> --content "# 追加内容" --mode append
  dws doc update --node <DOC_ID> --content "# 完整替换" --mode overwrite
Flags:
      --node string          文档 nodeId / URL
      --content string       Markdown 内容
      --content-file string  从文件读取 Markdown
      --mode string          更新模式: append / overwrite

上传文件到钉钉文档或钉钉知识库

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

导入本地文件为在线文档

详见 doc/doc-import.md。

Usage:
  dws doc import [flags]
  dws doc import get [flags]
Example:
  dws doc import --file ./report.docx
  dws doc import --file ./notes.md --folder <FOLDER_ID>
  dws doc import --file ./data.xlsx --workspace <WS_ID>
  dws doc import get --task-id <TASK_ID>
Flags:
      --file string        本地文件路径 (必填)
      --folder string      目标文件夹 ID 或 URL
      --workspace string   目标知识库 ID 或 URL
      --name string        导入后文档名称 (默认取文件名)
      --task-id string     导入任务 ID (import get 必填)

下载文件到本地（已迁移到 drive）

弃用提示：dws doc download 已迁移到 dws drive download（执行 doc download 会打印弃用警告）。下载已有文件（PDF/图片/附件等非在线文档）改用：

dws drive download --node <NODE_ID> --output ~/downloads/
dws drive download --node <NODE_ID> --output ./report.pdf

注意区分：在线文档（ALIDOC）导出为 docx 仍走 doc export（内容级命令，未迁移）；download 只下载已有文件。命令详情见 dingtalk-drive skill。

创建文件夹（已迁移）

弃用提示：dws doc folder create 已弃用。创建文件夹改用：

个人空间/钉盘 → dws drive mkdir --name "<名称>" [--folder <父节点>]

知识库内 → dws wiki node create --workspace <WS_ID> --name "<名称>" --type folder

命令详情见 dingtalk-drive skill。

复制文档/文件

Usage:
  dws doc copy [flags]
Example:
  dws doc copy --node <DOC_ID> --folder <TARGET_FOLDER_ID>
  dws doc copy --node <DOC_ID> --workspace <TARGET_WS_ID>
  dws doc copy --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --folder <FOLDER_ID>
Flags:
      --node string        源文档/文件 ID 或 URL (必填)
      --folder string      目标文件夹 ID 或 URL
      --workspace string   目标知识库 ID 或 URL (不传 --folder 时复制到该知识库根目录)

移动文档/文件

Usage:
  dws doc move [flags]
Example:
  dws doc move --node <DOC_ID> --folder <TARGET_FOLDER_ID>
  dws doc move --node <DOC_ID> --workspace <TARGET_WS_ID>
Flags:
      --node string        源文档/文件 ID 或 URL (必填)
      --folder string      目标文件夹 ID 或 URL
      --workspace string   目标知识库 ID 或 URL (不传 --folder 时移动到该知识库根目录)

重命名文档/文件

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   新名称 (必填)

查询块元素

Usage:
  dws doc block list [flags]
Example:
  dws doc block list --node <DOC_ID>
  dws doc block list --node <DOC_ID> --start-index 0 --end-index 5
  dws doc block list --node <DOC_ID> --block-type heading
Flags:
      --node string         文档 ID 或 URL (必填)
      --start-index int     起始位置 (从 0 开始)
      --end-index int       终止位置 (含)
      --block-type string   按块类型过滤

插入块元素

Usage:
  dws doc block insert [flags]
Example:
  dws doc block insert --node <DOC_ID> --text "这是一段文字"
  dws doc block insert --node <DOC_ID> --heading "二级标题" --level 2
  dws doc block insert --node <DOC_ID> --element '{"blockType":"paragraph","paragraph":{"text":"内容"}}'
  dws doc block insert --node <DOC_ID> --text "在此处之前插入" --ref-block <BLOCK_ID> --where before
Flags:
      --node string        文档 ID 或 URL (必填)
      --text string        快捷: 段落文本内容
      --heading string     快捷: 标题文本
      --level int          标题级别 1-6 (配合 --heading，默认 1)
      --element string     块元素 JSON (高级)
      --index int          参照位置索引 (从 0 开始)
      --where string       插入方向: before / after (默认 after)
      --ref-block string   参照块 ID (优先级高于 --index)

更新块元素

Usage:
  dws doc block update [flags]
Example:
  dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --text "新内容"
  dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}'
Flags:
      --node string        文档 ID 或 URL (必填)
      --block-id string    目标块 ID (必填)
      --text string        快捷: 段落文本内容
      --heading string     快捷: 标题文本
      --level int          标题级别 1-6 (配合 --heading，默认 1)
      --element string     块元素 JSON (高级)

删除块元素

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

Usage:
  dws doc block delete [flags]
Example:
  dws doc block delete --node <DOC_ID> --block-id <BLOCK_ID> --yes
Flags:
      --node string        文档 ID 或 URL (必填)
      --block-id string    目标块 ID (必填)

查询文档评论列表

Usage:
  dws doc comment list [flags]
Example:
  dws doc comment list --node <DOC_ID>
  dws doc comment list --node <DOC_ID> --type inline --resolve-status unresolved
  dws doc comment list --node <DOC_ID> --limit 20 --cursor <TOKEN>
Flags:
      --node string            目标文档的标识，支持传入 URL 或 ID (必填)
      --limit int              每页返回的评论数量，默认 50，最大 50
      --cursor string          分页游标，从上一次请求的返回结果中获取 (首次请求不传)
      --type string            按评论类型过滤: global (全文评论) / inline (划词评论)
      --resolve-status string  按解决状态过滤: resolved (已解决) / unresolved (未解决)

创建文档评论

Usage:
  dws doc comment create [flags]
Example:
  dws doc comment create --node <DOC_ID> --content "这里需要修改"
  dws doc comment create --node <DOC_ID> --content "请review" --mention uid1,uid2
Flags:
      --node string      目标文档的标识，支持传入 URL 或 ID (必填)
      --content string   评论的文字内容，纯文本 (必填)
      --mention string   被 @ 的用户 uid 列表，逗号分隔

创建划词评论 (内联评论)

Usage:
  dws doc comment create-inline [flags]
Example:
  dws doc comment create-inline --node <DOC_ID> --block-id <BLOCK_ID> --start 0 --end 10 --content "这里需要修改"
  dws doc comment create-inline --node <DOC_ID> --block-id <BLOCK_ID> --start 5 --end 20 --content "建议调整" --selected-text "被选中的原文"
  dws doc comment create-inline --node <DOC_ID> --block-id <BLOCK_ID> --start 0 --end 10 --content "请review" --mention uid1,uid2
Flags:
      --node string            目标文档的标识，支持传入 URL 或 ID (必填)
      --block-id string        评论锚定所在的块 ID (必填，可通过 dws doc block list 获取)
      --start int              选中文本在块内的起始字符偏移量，从 0 开始 (必填)
      --end int                选中文本在块内的结束字符偏移量，必须大于 start (必填)
      --content string         评论的文字内容，纯文本 (必填)
      --selected-text string   选中文本内容，填写后评论列表会展示「引用原文：xxx」
      --mention string         被 @ 的用户 uid 列表，逗号分隔

回复文档评论

Usage:
  dws doc comment reply [flags]
Example:
  dws doc comment reply --node <DOC_ID> --comment-key <COMMENT_KEY> --content "同意"
  dws doc comment reply --node <DOC_ID> --comment-key <COMMENT_KEY> --content "比心" --emoji
  dws doc comment reply --node <DOC_ID> --comment-key <COMMENT_KEY> --content "请确认" --mention uid1,uid2
Flags:
      --node string         目标文档的标识，支持传入 URL 或 ID (必填)
      --content string      回复的文字内容，表情回复时填写表情名称 (必填)
      --comment-key string  被回复评论的 commentKey，格式: {13位毫秒时间戳}{32位UUID}，可从 list/create 结果获取 (必填)
      --emoji               设为 true 时作为表情贴图回复 (默认 false)
      --mention string      被 @ 的用户 uid 列表，逗号分隔

更新文档评论

Usage:
  dws doc comment update --node <DOC_ID> --comment-key <COMMENT_KEY> --content <CONTENT> [--mention uid1,uid2]

commentKey 从 comment list/create/create-inline 返回中获取。只有显式传入 --mention 时才更新被 @ 用户列表。

删除文档评论

Usage:
  dws doc comment delete --node <DOC_ID> --comment-key <COMMENT_KEY> --yes

删除评论不可恢复，必须先获得用户明确确认，再添加全局 --yes。

文件内容获取路由规则

当用户请求"分析/查看/读取某个文件内容"时，必须先调用 dws doc info 获取文件元数据，再根据返回的 contentType 和 extension 字段选择对应链路：

contentType	extension	操作	命令
ALIDOC	adoc	在线获取 Markdown 内容	`dws doc read --node <ID>`
ALIDOC	axls	在线读取表格数据	`dws sheet list --node <ID>` → `dws sheet range read --node <ID>`
ALIDOC	able	在线查询多维表格记录	`dws aitable table get --base-id <BASE_ID>` → `dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID>`
非 ALIDOC	—	不支持在线分析	告知用户需下载到本地后查看

关键规则：非 ALIDOC 类型文件（PDF/Word/图片/视频等）不支持在线分析，用户可以选择下载后本地查看。

格式保留度声明（adoc ↔ markdown lossy projection）

dws doc read --format json 返回的 markdown 字段是钉钉 adoc 文档的有损投影。源 adoc 中以下富格式属性在 markdown 这一层没有对应表达，会被丢弃：

行高（row height）
单元格背景色（cell background color）
字体大小（font size）
字体颜色的渐变形态（radial-gradient / linear-gradient — 文本会以 <span style="color: radial-gradient(...)"> 字面保留，但 CSS color 不接受渐变，浏览器无法渲染，字符串保留但语义已死）
块级缩进 / 表格列宽
合并单元格状态
checkbox 视觉样式（颜色、形状）
任何 SVG / 嵌入式画板的渲染细节

硬指引（任何 contentType=ALIDOC 文档都适用）：

当用户要求"按模板生成同形态变体 / 参照这个生成 / 复刻 / 仿照这个文档"时，禁止走 doc read → create_file → doc create 链路——这条链路会做两次 lossy projection（adoc → markdown 丢一次，markdown → adoc 重建再丢一次），最终交付物只有文本内容，富格式全部失真。
正确路径：dws doc copy（adoc 层面整文档保形复制）+ dws doc rename + dws doc block list / dws doc block update（在副本上做局部修改）。详见 best_practices/04-document.md 的 template-based-generation recipe。
当用户提到 行高 / 颜色 / 字号 / 表格样式 / 周末高亮 等富格式诉求时，agent 必须在动手前显式声明能力边界："这些属性 markdown 无法表达，需走 copy + block update 路径"，避免静默走破坏链。

内容写入管道（create / update 共用）

关键原则：CLI 内置自动分片。超长内容（>10000 字符）自动按 markdown 结构切分后逐片写入，对调用方透明。写入完成后由调用方自行决定是否回读确认。

输入方式选择

场景	推荐方式	说明
短文本（<2KB，无换行/表格/特殊字符）	`--content "..."`	字面量传入，最简单
长文本（≥2KB）、含换行、含表格	`--content-file ./file.md`	必须用文件路径，避免 shell escape 和截断
含特殊字符（`"`、`\`、`$`、`）	`--content-file ./file.md`	字面量传入会被 shell 转义破坏
管道/heredoc 输入	`--content -` 或 `cat file \| dws doc ...`	从 stdin 读取

自动分片行为

当内容超过 10000 字符时，CLI 自动执行：

create: 先创建空文档拿 nodeId，再按 markdown 标题边界切分后逐片 append
update (overwrite): 第一片用 overwrite，后续片用 append
update (append): 所有片段用 append

分片策略按优先级：H1 标题 → H2 标题 → H3 标题 → 空行（段落边界）→ 硬切（保留表格/代码块完整性）

如果某片写入超时，自动将分片大小减半重试（最小 5000 字符，低于此值报错）。

输出格式

写入成功后输出 JSON（混合 [INFO] 进度行）：

{"success": true, "nodeId": "xxx", "chunksWritten": 3}

字段	说明
`nodeId`	文档节点 ID，可用于后续读取或追加
`chunksWritten`	实际写入的分片数（1 = 单次写入）

内容完整性验证（必读）

CLI 不会自动执行回读验证。Agent 必须在文档写入完成后主动回读确认——这是硬约束，不是建议：

使用 dws doc read --node <nodeId> 读取写入后的文档内容
检查关键段落是否完整、顺序是否正确
如发现内容缺失或异常，使用 dws doc update --mode append 补写缺失部分

何时回读：每次 create / update 操作完成后必须回读。

单次写入（≤10000 字符）：写完立即回读一次

分片写入（>10000 字符）：所有分片写完后回读一次全文，校验关键标题与段落完整性

破坏性 overwrite（--mode overwrite --yes）：必须回读，确认 overwrite 未被后端静默降级为 append（详见 best_practices/04-document.md "doc update 回读校验规范"）

连续多次编辑同一文档：可在全部编辑完成后统一回读一次

禁止在未回读的情况下直接向用户报告"已完成 / 更新成功"。Agent 自陈"完成"必须基于回读结果，而非工具调用的 success=true 字段。

进度输出示例

[INFO] 内容较长 (25000 字符)，自动分片写入...
[INFO] 已创建空文档 (nodeId=abc123)，开始分片写入...
[INFO] 写入分片 (1/3)，10000 字符...
[INFO] 写入分片 (2/3)，10000 字符...
[INFO] 写入分片 (3/3)，5000 字符...
[INFO] 全部 3 个分片写入完成
{"success": true, "nodeId": "abc123", "chunksWritten": 3}

CONTENT_TRUNCATED 错误

当分片写入持续超时且减半到最小阈值仍失败时，返回 CONTENT_TRUNCATED 错误码。应对策略：

检查网络和后端服务状态
已写入的部分内容可通过 dws doc read --node <NODE_ID> 查看
从断点处手动用 dws doc update --mode append 继续追加

删除文档/文件到回收站

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

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

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

下载文档附件

Usage:
  dws doc media download [flags]
Example:
  dws doc media download --node <DOC_ID> --resource-id <RESOURCE_ID>
  dws doc media download --node "https://alidocs.dingtalk.com/i/nodes/xxx" --resource-id <RESOURCE_ID>
Flags:
      --node string          目标文档的标识，支持传入 URL 或 ID (必填)
      --resource-id string   附件资源 ID，可通过 dws doc block list 获取 (必填)

上传附件并插入文档

Usage:
  dws doc media insert [flags]
Example:
  dws doc media insert --node <DOC_ID> --file ./report.pdf
  dws doc media insert --node <DOC_ID> --file ./data.bin --name "数据文件.dat" --mime-type application/octet-stream
  dws doc media insert --node <DOC_ID> --file ./image.png --ref-block <BLOCK_ID> --where before
Flags:
      --node string        目标文档的标识，支持传入 URL 或 ID (必填)
      --file string        本地文件路径 (必填)
      --name string        附件显示名称 (默认使用文件名)
      --mime-type string   文件 MIME 类型 (默认根据扩展名推断)
      --index int          插入位置索引
      --where string       相对位置: before / after (配合 --ref-block)
      --ref-block string   参考块 ID (配合 --where)

��加文档权限（节点级授权）

Usage:
  dws doc permission add [flags]
Example:
  dws doc permission add --node <DOC_ID> --users uid1 --role READER
  dws doc permission add --node <DOC_ID> --users uid1,uid2 --role EDITOR
  dws doc permission add --node "https://alidocs.dingtalk.com/i/nodes/<DOC_UUID>" --users uid1 --role MANAGER
Flags:
      --node string        目标文档/文件夹的 ID 或 URL (必填)
      --users strings      被授权的用户 userId 列表，逗号分隔 (必填，单次最多 30 个)
      --role string        授予的角色 (必填，大小写敏感，必须全大写): MANAGER (管理者) / EDITOR (可编辑) / DOWNLOADER (可下载) / READER (可阅读)
      --workspace string   所属知识库 ID (选填，仅用于辅助构造返回的 docUrl，业务实际依赖 nodeId)

重要约束：

仅支持 USER 类型授权。

角色枚举严格大写：MANAGER / EDITOR / DOWNLOADER / READER（OWNER 不可通过此接口添加）。

操作者需在该节点具备「可编辑（EDITOR）」及以上角色（OWNER / MANAGER / EDITOR）。

授权对象是文档节点本身，不需要也不应该用 wiki member add（那个是知识库容器级授权）。

修改文档权限（节点级）

Usage:
  dws doc permission update [flags]
Example:
  dws doc permission update --node <DOC_ID> --users uid1 --role EDITOR
  dws doc permission update --node <DOC_ID> --users uid1,uid2 --role READER
Flags:
      --node string        目标文档/文件夹的 ID 或 URL (必填)
      --users strings      目标用户 userId 列表，逗号分隔 (必填，单次最多 30 个)
      --role string        新角色 (必填，大小写敏感，必须全大写): MANAGER / EDITOR / DOWNLOADER / READER
      --workspace string   所属知识库 ID (选填)

列出文档权限（节点级）

Usage:
  dws doc permission list [flags]
Example:
  dws doc permission list --node <DOC_ID>
  dws doc permission list --node <DOC_ID> --limit 50
  dws doc permission list --node <DOC_ID> --filter-role EDITOR
Flags:
      --node string          目标文档/文件夹的 ID 或 URL (必填)
      --workspace string     所属知识库 ID (选填)
      --limit int             返回数量上限，最大 200 (默认 50)
      --filter-role string   按角色过滤: MANAGER / EDITOR / DOWNLOADER / READER (选填)

接口不支持游标分页，使用 --limit 一次性拉取。

导出在线文档为 docx（一体化命令）

Usage:
  dws doc export [flags]
Example:
  dws doc export --node "https://alidocs.dingtalk.com/i/nodes/xxx" --output ./exported.docx
  dws doc export --node <DOC_ID> --output ~/downloads/
Flags:
      --node string           要导出的文档标识，支持文档 URL 或 dentryUuid (必填)
      --output string         本地保存路径，文件路径或目录 (必填)
      --export-format string  导出格式，当前仅支持 docx (默认)

CLI 内部自动完成：提交导出任务 → 渐进式退避轮询（最多约 5 分钟）→ 成功后自动下载文件。 只需一条命令，无需手动轮询。

查询导出任务结果（手动兜底）

Usage:
  dws doc export get [flags]
Example:
  dws doc export get --job-id <JOB_ID>
Flags:
      --job-id string   导出任务 ID (必填)

仅在 dws doc export 超时或中断后，用于手动查询任务状态。通常不需要调用。

URL 识别与 DOC_ID 提取

当用户输入包含钉钉文档 URL 时，必须先识别并提取 DOC_ID，再判断意图。

补充：如果这是用户直接提供的原始 alidocs URL，必须先按链接规范 probe 一次确认真实类型，再判断是否继续走 doc。

支持的 URL 格式

格式	示例	DOC_ID 提取方式
`alidocs.dingtalk.com/i/nodes/{id}`	`https://alidocs.dingtalk.com/i/nodes/9E05BDRVQePjzLkZt2p2vE7kV63zgkYA`	取 URL 路径最后一段：`9E05BDRVQePjzLkZt2p2vE7kV63zgkYA`
`alidocs.dingtalk.com/i/nodes/{id}?queryParams`	`https://alidocs.dingtalk.com/i/nodes/abc123?doc_type=wiki_doc`	忽略 query 参数，取路径最后一段：`abc123`
`alidocs.dingtalk.com/document/{edit\|preview}?...&dentryKey={key}`	`https://alidocs.dingtalk.com/document/edit?dentryKey=wo1g3x54FzVEJ5yE`	不要提取 `dentryKey` 单独使用，必须将完整 URL 原样传给 `--node`

提取规则

匹配 URL 中 alidocs.dingtalk.com 域名
路径为 /i/nodes/{id} 时，取 URL path 的最后一段作为 DOC_ID（去掉 query string 和 fragment）
路径为 /document/edit 或 /document/preview 且 query 含 dentryKey 时，禁止提取 dentryKey 当 DOC_ID；将整段 URL 原样传给 --node，CLI 会自动解析（追踪参数如 utm_source、chInfo 也不必清理）
提取出的 DOC_ID 可直接用于所有 --node 参数，也可将完整 URL 传给 --node（CLI 会自动解析）

ID 边界与参数映射

nodeId 是 doc 命令的统一节点标识；文档、文件夹、文件都通过 nodeId 或完整 alidocs URL 传给 --node / --folder。
dentryUuid 是 alidocs URL /i/nodes/{dentryUuid} 的最后一段，在 doc 场景中等价于可传入 CLI 的 nodeId；不要把它改写成数字 ID。
dentryId 通常是纯数字，不是 doc 的 nodeId，也不是 doc --folder 的目标文件夹 ID；不要把数字 dentryId 当作 --node、--folder，也不要当作隐藏兼容 alias（如 --parent-id / --parent-folder-id）的取值。
目标父文件夹的 canonical flag 是 --folder <folderNodeId或folderUrl>，目标知识库使用 --workspace <workspaceId或workspaceUrl>。CLI 可能接受 --parent-id / --parent-folder-id 作为隐藏兼容 alias，但 skill 正文和示例应统一教 --folder，不要把 drive/chat 链路里的数字 parentId 搬到 doc 命令。
如果上下文只有数字 dentryId，但用户要读、改、移动、复制、重命名文档，先通过 drive search / drive list / 用户提供的 alidocs URL 获取 nodeId / dentryUuid，不要用数字 dentryId 重试为父目录参数。

处理流程

用户输入含 alidocs.dingtalk.com URL
  → 若是用户直接提供的原始 URL，先按链接规范做 probe
  → 提取 DOC_ID（URL 路径最后一段）
  → 结合用户意图选择命令（doc 默认 read，folder 默认 drive list，file 默认 drive download）
  → 将 DOC_ID 传给 --node 参数

意图判断

用户说"找文档/搜文档/最近文档":

搜索 → dws drive search（全局）或 dws wiki node search --workspace <id>（指定知识库）
浏览 → dws drive list（doc search / doc list 已弃用，见本文顶部「搜索 / 遍历文件」）

用户说"看文档/读内容/文档内容":

读取 → read (需文档 ID 或 URL)
元信息 → info

用户说"写文档/创建文档":

新建文字文档（adoc）→ doc create
追加内容 → update --mode append
整篇覆盖替换 → 先 update --mode overwrite --dry-run 预览，用户确认后再 update --mode overwrite --yes
指定父目录时，只有明确的文档文件夹 nodeId / alidocs 文件夹 URL 才能放入 --folder；上一步若只返回了纯数字 dentryId、spaceId 或 drive parent-id，不要把它传给 doc 的 --folder

严禁把「创建表格」路由到 doc create：

用户说"创建表格/新建表格/建个电子表格/在线表格" → 走 dws sheet create（axls 在线电子表格）

用户说"创建多维表格/新建 AI 表格/建 base/数据库表" → 走 dws aitable base create（able 多维表格）

用户说"新建脑图/白板/多维表/演示文稿":

用 dws wiki node create --workspace <WS_ID> --type <type> 指定类型 (axls/amind/adraw/able/appt)；doc file create 已弃用
注意 wiki node create 必须带 --workspace（知识库上下文）

用户说"建文件夹/新建目录":

个人空间/钉盘 → dws drive mkdir --name "<名称>"
知识库内 → dws wiki node create --workspace <WS_ID> --type folder（doc folder create / doc file create --type folder 已弃用）

用户说"上传文件/传文件/上传到文档/上传到知识库":

上传 → upload（需本地文件路径）
上传并转换 → upload --convert

用户说"导入文件/导入为在线文档/导入 Word/导入 Excel/导入 xmind/导入 Markdown/把本地文件转在线文档":

导入并转换为在线文档 → doc import --file <本地路径>
支持 docx/doc/xlsx/xls/md/txt/xmind/mark，文件大小不超过 20MB
如果用户指定知识库或文件夹，补充 --workspace 或 --folder
不要把本地文件内容先读出来再 doc create/update；应直接使用 doc import

用户说"下载/导出/下载到本地/导出文档/导出为Word/导出为docx/把文档导出来":

必须先判断目标文件类型，再决定走 doc export 还是 drive download：
- 在线文档（alidocs/adoc）→ doc export（内容级命令，格式转换后导出为 docx，未迁移）
- 已有文件（PDF、图片、附件、视频等非在线文档）→ drive download（doc download 已弃用）
判断方法：
1. 用户明确说"导出文档"/"导出为 Word/docx" → 直接走 doc export
2. 用户明确说"下载 PDF/图片/附件" → 直接走 drive download
3. 不确定时，先用 doc info --node <ID> 查询节点信息，根据 contentType 判断：
  - contentType = ALIDOC → 走 doc export
  - contentType = DOCUMENT/IMAGE/VIDEO 等 → 走 drive download

严禁将"导出文档"直接路由到 drive download。drive download 只能下载已有文件（原样下载），doc export 是将在线文档格式转换后导出为 docx，两者完全不同。

用户说"复制文档/拷贝一份/复制到":

复制 → copy (需源 --node 和目标 --folder/--workspace)

用户说"移动文档/搬到/移到/转移文件":

移动 → move (需源 --node 和目标 --folder/--workspace)

用户说"重命名/rename/改名/改文档名/修改文档名称/修改文档标题/把这个文档叫做...":

重命名 → doc rename（需文档 ID 或 URL + 新名称）
只要意图是修改文档在列表和链接中展示的名称，统一路由到 dws doc rename --node <DOC_ID_OR_URL> --name "新名称"；不要走 drive、doc update 或重新 doc create
只有用户明确说"正文里的标题/章节标题/段落标题/H1 标题"时，才走 block update

用户说"删除文档/删掉这个文件/移到回收站/丢掉这篇文档":

删除节点 → delete（危险操作，需 --yes 确认；需文档 ID 或 URL）

用户说"插入附件/上传附件到文档/往文档里加文件/加附件":

插入附件 → media insert（需文档 ID 或 URL + 本地文件路径）

用户说"插入图片/加图片/放张图/嵌入图片/往文档里插图":

插入图片 → media insert（需文档 ID 或 URL + 本地图片文件路径）
注意：图片也是通过 media insert 作为附件块插入文档，不是通过 block insert

用户说"下载附件/获取附件/取出文档里的附件":

下载附件 → media download（需文档 ID 或 URL + 资源 ID）

用户说"编辑块/改段落/插入标题/删除块":

查看结构 → block list
插入 → block insert
修改 → block update
删除 → block delete

用户说"给某人开权限/分享给某人/授权某文档/把这篇文档给 xxx 看":

新增权限 → permission add（需 --node + --user + --role）
修改权限 → permission update
查看谁有权限 → permission list

关键区分：

"把某篇文档授权给某人" → doc permission add（节点级，包括「我的文档」下的文档都支持）

"把某个知识库整体授权给某人" → wiki member add（容器级，但**「我的文档」个人空间不支持**）

补充：如果用户直接粘贴的是原始 alidocs URL，先按链接规范 probe；只有 probe 确认是 adoc / file / folder 后，才继续按下列意图执行。

用户直接粘贴文档 URL（无其他指令）:

默认 → read（读取文档内容）
如 URL 明显是文件夹 → drive list（列出文件夹内容；doc list 已弃用）

用户粘贴 URL + 附加指令:

"帮我看看这个文档" → read
"这个文档的信息" → info
"往这个文档追加内容" → update --mode append
"把这个文档标题改成 X" / "这个文档改名为 X" → rename
"把正文里的一级标题/章节标题改成 X" → block update

关键区分: doc(文档编辑/阅读) vs aitable(数据表格操作) vs drive(钉盘文件管理)