从钉钉知识库导出文档到 TorchV AIS

本文介绍如何使用钉钉 DWS 命令行工具，将钉钉知识库中的在线文档导出为本地 Office 文件，再上传到独立部署的 TorchV AIS 知识库。

图1：首先在钉钉知识库里面创建了一个新的知识库AIS，然后新建了两个文档。

图2：自动导出成功之后，两个文档已经在我指定的AIS知识库目录中。

本文以已经跑通的测试为例：

• 钉钉知识库：AIS
• 钉钉空间链接：https://alidocs.dingtalk.com/i/spaces/BpLm*********X2g/overview
• 测试文档：水星1号、火星1号
• AIS目标目录：卢向东的个人知识库/钉钉知识库导入存放目录

本教程重点说明导出、上传和验证流程，不讨论 AIS 对特定 Office 文件的解析兼容性。

一、整体流程

钉钉 OAuth 登录
    ↓
解析知识库 workspaceId
    ↓
列出知识库节点
    ↓
读取节点类型
    ├─ adoc：导出为 DOCX / Markdown / PDF
    ├─ axls：导出为 XLSX
    └─ 普通附件：原文件下载
    ↓
保存到本地 staging 目录
    ↓
上传到 AIS 指定目录
    ↓
按 AIS 文档编码读回验证

二、准备条件

1. 本地环境

需要准备：

• Node.js 16.7 或更高版本；
• npm；
• 可以登录钉钉的浏览器；
• 可以访问 AIS 的网络环境；
• 已配置可用的 AIS Open Key。

检查 Node.js 和 npm：

node --version
npm --version

2. 创建同步项目

mkdir -p dingtalk-ais-sync
cd dingtalk-ais-sync
npm init -y
npm install --save-exact dingtalk-workspace-cli@1.0.59
mkdir -p staging state

定义本教程使用的命令路径：

SYNC_PROJECT="$(pwd)"
DWS_BIN="$SYNC_PROJECT/node_modules/.bin/dws"
AIS_KB_BIN="/Users/lu/Documents/Codex/.agents/bin/ais-kb.sh"

验证 DWS：

"$DWS_BIN" version
"$DWS_BIN" auth status --format json

三、登录钉钉并授权

执行：

"$DWS_BIN" auth login

浏览器会打开钉钉登录和授权页面。完成扫码、登录和企业授权。

本场景只需要以下四个业务域：

• wiki：查询知识库及节点；
• doc：导出在线文字文档；
• sheet：导出在线电子表格；
• drive：获取文档存储信息和下载普通附件。

如果授权界面默认选择了其他业务域，应取消与本任务无关的权限。

登录后检查状态：

"$DWS_BIN" auth status --format json

应重点检查：

{
  "authenticated": true,
  "token_valid": true,
  "refresh_token_valid": true
}

OAuth 方式适合功能验证。正式生产同步建议使用企业内部应用，并只申请需要的只读权限。

四、解析钉钉知识库

1. 根据知识库链接获取 workspaceId

DINGTALK_SPACE_URL="https://alidocs.dingtalk.com/i/spaces/BpLm*********X2g/overview"

"$DWS_BIN" wiki +space-get \
  --workspace "$DINGTALK_SPACE_URL" \
  --format json

本次返回的关键内容：

{
  "name": "AIS",
  "workspaceId": "BpLm*********X2g"
}

保存空间ID：

DINGTALK_WORKSPACE_ID="BpLm*********X2g"

不要仅凭 URL 结构猜测 workspaceId，应以接口返回为准。

2. 列出知识库全部节点

"$DWS_BIN" wiki +node-list \
  --workspace "$DINGTALK_WORKSPACE_ID" \
  --page-all \
  --max-items 500 \
  --format json

全量读取时应确认：

• autoPageComplete=true；
• hasMore=false；
• 返回的节点数量符合预期。

本次得到两个节点：

名称	nodeId
水星1号	gpG2NdyVXQg*******7LY3AD0JMwvDqPk
火星1号	QPGYqjpJYRY******7OOM68akx1Z5N

五、识别节点类型

分别读取节点元数据：

"$DWS_BIN" wiki +node-get \
  --node "gpG2NdyVXQg*******7LY3AD0JMwvDqPk" \
  --format json

"$DWS_BIN" wiki +node-get \
  --node "QPGYqjpJYRY******7OOM68akx1Z5N" \
  --format json

重点读取 extension：

extension	内容类型	导出方式
adoc	钉钉在线文字文档	dws doc +export
axls	钉钉在线电子表格	dws sheet export
xlsx、docx、pdf 等	普通文件	dws drive download

本次识别结果：

• 水星1号：axls；
• 火星1号：adoc。

不要把在线表格当作普通文件下载，也不要把在线文字文档交给表格命令处理。

六、导出到本地

所有导出文件统一放在 staging/ 目录。

1. 导出在线电子表格

"$DWS_BIN" sheet export \
  --node "gpG2NdyVXQg*******7LY3AD0JMwvDqPk" \
  --output "./staging/水星1号.xlsx" \
  --format json

sheet export 会自动完成提交任务、轮询状态和下载，不需要在外部编写轮询程序。

2. 导出在线文字文档

"$DWS_BIN" doc +export \
  --node "QPGYqjpJYRY******7OOM68akx1Z5N" \
  --export-format docx \
  --output "./staging/火星1号.docx" \
  --format json

文字文档也可以导出为：

docx
markdown
pdf

必须显式传入 --export-format。

3. 检查导出文件

file ./staging/水星1号.xlsx ./staging/火星1号.docx
shasum -a 256 ./staging/水星1号.xlsx ./staging/火星1号.docx

建议记录：

• 钉钉 workspaceId；
• nodeId；
• 源文档更新时间；
• 导出格式；
• 文件大小；
• SHA-256；
• 导出任务 jobId。

七、上传到 AIS

1. 检查目标目录

"$AIS_KB_BIN" \
  "kb tree 卢向东的个人知识库/钉钉知识库导入存放目录/ --depth 2 --limit 50"

本次 AIS 目标目录编码为：

20914******22619392

2. 上传 XLSX

"$AIS_KB_BIN" \
  --upload-file "$SYNC_PROJECT/staging/水星1号.xlsx" \
  --path-name "/卢向东的个人知识库/钉钉知识库导入存放目录"

3. 上传 DOCX

"$AIS_KB_BIN" \
  --upload-file "$SYNC_PROJECT/staging/火星1号.docx" \
  --path-name "/卢向东的个人知识库/钉钉知识库导入存放目录"

上传成功后，接口会返回 AIS 稳定文档编码。此次结果为：

文件	AIS文档编码
水星1号.xlsx	2091437*****02834432
火星1号.docx	2091437*****6623104

八、验证 AIS 导入结果

1. 验证目录结构

"$AIS_KB_BIN" \
  "kb tree 卢向东的个人知识库/钉钉知识库导入存放目录/ --depth 2 --limit 50"

确认两个文件都已出现在目标目录。

2. 按稳定编码读取解析内容

"$AIS_KB_BIN" \
  "kb cat --code 2091437*****02834432 --head 120"

"$AIS_KB_BIN" \
  "kb cat --code 2091437*****6623104 --head 120"

如果返回“文件转换中”，等待 AIS 完成知识加工后，再使用同一个文档编码重新读取。

不能只根据上传接口的 SUCCESS 判断整个导入完成；只有目录中存在文件并且 kb cat 能读取解析结果，才算完成了端到端验证。

九、保存同步清单

建议为每个源文档记录以下信息：

{
  "sourceSystem": "dingtalk",
  "workspaceId": "BpLmk*******6X2g",
  "sourceNodeId": "gpG2NdyVXQg*******7LY3AD0JMwvDqPk",
  "sourceName": "水星1号",
  "sourceExtension": "axls",
  "sourceUpdatedAt": "2026-08-23T15:39:09+08:00",
  "exportFormat": "xlsx",
  "localFile": "staging/水星1号.xlsx",
  "sha256": "86a0187680cfad73cf4**************184b67bad9547ea7e5852a4787f784f",
  "aisDirectoryCode": "20914**********19392",
  "aisDocumentCode": "209*********834432",
  "syncStatus": "SUCCESS"
}

后续同步不能只用文件名判断是否为同一文档，应以钉钉 nodeId 作为源对象主键。

十、常见问题

1. DWS显示“未登录”

重新执行：

"$DWS_BIN" auth login

如果提示企业没有启用 CLI 数据访问，需要在浏览器提交申请，并由企业管理员批准。

2. 知识库链接中的ID是否就是 workspaceId

不能直接假定。应执行 wiki +space-get，使用真实返回的 workspaceId。

3. 找不到文档

检查：

• 是否登录了正确的企业组织；
• 当前用户是否有知识库访问权限；
• node-list 是否完成全部分页；
• 文档是否位于子目录，必要时继续列出对应 folderId 下的节点。

4. 导出命令应该选哪一个

先执行 wiki +node-get：

• extension=adoc：使用 doc +export；
• extension=axls：使用 sheet export；
• 普通 Office/PDF 文件：使用 drive download。

5. AIS上传成功但暂时无法读取

Office 文件上传后需要经过解析、清洗和知识加工。出现“文件转换中”时，保留文档编码，稍后重新执行 kb cat --code <AIS文档编码>。

十一、从POC升级到生产同步

本教程使用个人 OAuth 登录，适合验证可行性。生产环境建议增加：

1. 创建钉钉企业内部应用，采用服务端身份运行；
2. 只申请知识库、文档、表格和文件下载所需的最小只读权限；
3. 使用 nodeId + updateTime + SHA-256 判断内容是否变化；
4. 保存钉钉节点与 AIS 文档编码之间的映射；
5. 增加定时任务、失败重试、限流和审计日志；
6. 同步处理源文档删除、移动和权限收回；
7. 在正式发布给 Agent 前完成 AIS 侧权限映射和内容审核。

十二、最短命令清单

# 登录
"$DWS_BIN" auth login

# 解析知识库
"$DWS_BIN" wiki +space-get --workspace "$DINGTALK_SPACE_URL" --format json

# 列出节点
"$DWS_BIN" wiki +node-list --workspace "$DINGTALK_WORKSPACE_ID" --page-all --max-items 500 --format json

# 查看节点类型
"$DWS_BIN" wiki +node-get --node "<NODE_ID>" --format json

# 导出在线文字文档
"$DWS_BIN" doc +export --node "<NODE_ID>" --export-format docx --output "./staging/文档.docx" --format json

# 导出在线电子表格
"$DWS_BIN" sheet export --node "<NODE_ID>" --output "./staging/表格.xlsx" --format json

# 上传 AIS
"$AIS_KB_BIN" --upload-file "$SYNC_PROJECT/staging/文件名" --path-name "/知识库/目标目录"

# 读取验证
"$AIS_KB_BIN" "kb cat --code <AIS文档编码> --head 120"

完成以上步骤，即可建立“钉钉知识库 → 本地标准文件 → 独立部署 AIS”的基本导入链路。