dc-docs/docs/how-to-replicate.md

从钉钉群聊到知识库：飞书文档自动采集与结构化系统 - 复刻指南

作者：大师 | 日期：2026-06-03

---

一句话说清楚这个项目做了什么

从钉钉群聊消息中自动抓取飞书文档链接和文件附件，下载内容，构建知识图谱和 Obsidian 知识库。

整个流程 = 3个核心工具 + 6个Python脚本，不需要自己写任何API对接代码。

---

整体架构

钉钉群聊消息
    |
    v
(1) dws CLI（悟空）-- 拉取钉钉消息、下载文件附件
    |
    v
(2) Python 脚本 -- 正则提取飞书链接 + 文件ID
    |
    v
(3) lark-cli -- 读取飞书文档内容（Block API）
    |
    v
(4) Python 脚本 -- 构建知识图谱（JSON）、Obsidian 库、汇总报告

关键认知：你不需要申请飞书开放平台的App。 消息来源是钉钉（通过dws），飞书文档内容获取通过lark-cli（浏览器授权登录即可）。

---

核心工具获取指南

工具 1：dws CLI -- 钉钉消息采集（随悟空自动安装）

是什么：dws CLI 是钉钉「悟空」(Wukong) 桌面客户端自带的命令行工具，封装了钉钉 25+ 项 MCP 服务（群聊消息、文件管理、日历、通讯录、审批等），无需自己对接钉钉开放平台API。

获取方式（三种，选一种即可）：

方式	适合谁	操作
GitHub 直接下载（推荐）	所有人	从 GitHub Releases 下载对应平台的压缩包，解压即用
安装悟空客户端	钉钉重度用户	装完悟空，dws 自动在 C:\Program Files\Wukong\<版本>\bin\dws.exe
从同事那里复制	最省事	复制一个 dws.exe 文件（约 5-14MB）

GitHub 仓库：https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli

这是钉钉官方开源的 CLI 工具，2000+ stars，持续更新中（最新 v1.0.33，2026-06-02 发布）。

# 从 GitHub Releases 直接下载（以 Windows 为例）：
# https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/latest
# 下载 dws-windows-amd64.zip（约 5.3MB），解压得到 dws.exe

# macOS / Linux 也有对应版本：
# dws-darwin-amd64.tar.gz  (macOS Intel)
# dws-darwin-arm64.tar.gz  (macOS Apple Silicon)
# dws-linux-amd64.tar.gz   (Linux x64)

```bash
# 悟空是钉钉的AI桌面客户端（也叫钉钉Real版），安装后自动附带：
# - dws CLI（钉钉MCP服务命令行）
# - wukong-cli（悟空Agent命令行）
# - Node.js、Python、ffmpeg 等运行时
#
# 安装路径参考：
#   主程序：C:\Program Files\Wukong\<版本号>\DingTalkReal.exe
#   dws CLI：C:\Program Files\Wukong\<版本号>\bin\dws.exe
#   运行时缓存：C:\Users\<用户名>\.real\.bin\dws\bin\dws.exe

版本信息（本项目实际使用）：

项目	值
悟空版本	0.9.51
dws CLI 版本	0.2.75（悟空内置）/ 1.0.33（GitHub 最新）
架构	MCP Dynamic Aggregation
Go 版本	1.24+

认证：首次使用需要登录认证（钉钉扫码或账号登录），Corp ID 和 User ID 会自动配置。运行 dws auth status 可查看登录状态。

能把 dws 单独提取出来用吗？可以。

dws.exe 是 Go 语言静态编译的二进制文件（14MB），不依赖任何外部 DLL，可以脱离悟空独立运行。提取方法：

# 只需要一个文件：dws.exe（14MB）
# 路径：C:\Program Files\Wukong\<版本号>\bin\dws.exe
#   或：C:\Users\<用户名>\.real\.bin\dws\bin\dws.exe

# 1. 复制 dws.exe 到任意目录
copy "C:\Users\admin\.real\.bin\dws\bin\dws.exe" D:\tools\dws.exe

# 2. 首次运行，触发认证（会自动创建 .dws 数据目录）
D:\tools\dws.exe auth status
# 如果未登录，会提示 OAuth 扫码登录（用钉钉App扫码）

# 3. 认证成功后，目录下会自动生成 .dws/ 子目录：
#    .dws/identity.json  -- 身份标识
#    .dws/token.json     -- Token（自动续期）
#    .dws/.data           -- 加密凭证
#    .dws/logs/           -- 日志

# 4. 验证可用
D:\tools\dws.exe chat message list --help
D:\tools\dws.exe drive download --help

提取后的体积：

文件	大小
dws.exe	14 MB
.dws/ 数据目录	< 1 MB
总计	约 14 MB

认证机制详解（dws 自带，不需要悟空）：

dws 内置了完整的 OAuth 认证流程，提取出来后独立就能完成登录：

运行 dws auth status（未登录状态）
    -> dws 启动 Device Flow OAuth
    -> 连接 login.dingtalk.com/oauth2/auth
    -> 终端显示二维码 / URL
    -> 用钉钉App扫码授权
    -> dws 轮询 api.dingtalk.com 获取 Token
    -> Token 加密存储到 .dws/.data
    -> 完成

dws 内置了默认的 OAuth ClientID/ClientSecret，普通用户直接用就行，不需要自己申请。如果公司有自建应用，也可以通过环境变量覆盖：

# 可选：使用自建应用的凭证（一般不需要）
export DWS_CLIENT_ID=<你的AppKey>
export DWS_CLIENT_SECRET=<你的AppSecret>

注意事项：

• Token 会自动续期，但长时间不用会过期，重新运行 dws auth status 触发重新扫码即可
• 每个人需要用自己的钉钉账号认证，不能共用 Token
• 提取出来的 dws 功能完整，支持全部 25+ 项 MCP 服务
• .dws/.data 是加密存储的凭证文件（511字节），不要分享给别人

核心能力：

命令	用途	示例
dws chat message list	拉取群聊消息	dws chat message list --group <群ID> --time "2026-05-01" --format json --limit 200
dws drive download	下载文件附件	dws drive download --node <fileId> --output ./files/

获取群组ID：需要知道目标群的 openConversationId，可以通过以下方式获取：

• 在钉钉管理后台查看
• 或者先用 dws chat group list 命令列出你所在的群

分页策略：API 每次最多返回约200条消息，超过的话需要分段拉取 + 用 openMessageId 去重：

# 分段拉取示例
segments = [
    ("2026-05-01 00:00:00", "true"),   # 从5月1日向前
    ("2026-05-19 00:00:00", "true"),   # 从5月19日向前
    ("2026-05-24 00:00:00", "true"),   # 从5月24日向前
    ("2026-06-03 00:00:00", "false"),  # 从6月3日向后
]
# forward="true" 表示从该时间点向前（更新的消息）
# forward="false" 表示从该时间点向后（更旧的消息）

---

工具 2：lark-cli -- 飞书文档内容读取

是什么：飞书官方提供的命令行工具，通过浏览器 OAuth 授权后，可以直接调用飞书 Open API 读取文档内容。

安装：

# 需要 Node.js 18+
npm install -g @larksuite/cli

# 验证安装
lark-cli --version

认证配置（关键步骤）：

# 1. 初始化配置
lark-cli config init

# 2. 浏览器授权登录（会自动打开浏览器）
lark-cli auth login --domain docs,drive,wiki --recommend

# 3. 验证授权状态
lark-cli auth status

为什么能拿到飞书文档内容？

这是大家最关心的问题，答案是：

1. lark-cli 使用浏览器 OAuth 授权：你在浏览器里登录自己的飞书账号，lark-cli 拿到你的访问令牌（token）。
2. 用你的身份调飞书 Open API：后续所有请求都是以你个人身份发出的，跟你在浏览器里打开文档一样。
3. 你有权限看的文档，lark-cli 就能读：不是破解，不是爬虫，就是正常的API调用。

你（浏览器登录飞书）-> OAuth Token -> lark-cli -> 飞书 Open API -> 文档内容

核心命令：

# 获取文档内容（Block API，返回JSON格式）
lark-cli api GET /open-apis/docx/v1/documents/<doc_id>/blocks --format json

# doc_id 从飞书链接中提取：
# 例：https://dianchukeji.feishu.cn/docx/AbLed72FgoPn5hxOYN3cRpffn0E
#                                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 这就是 doc_id

注意事项：

• Token 有过期时间，长时间不用需要重新授权
• 你只能读取你有权限的飞书文档（跟在浏览器里访问一样）
• wiki 类型的链接需要先解析真实的 doc_id（wiki 链接里的ID是节点ID，不是文档ID）

---

工具 3：Python 脚本 -- 数据处理管线

依赖安装：

pip install beautifulsoup4 requests

7个脚本的职责：

脚本	输入	输出	干什么
fetch_all.py	dws CLI	data/raw-messages/all_messages_combined.json	拉取两个群的全部消息
extract_links.py	上一步的JSON	终端输出（统计信息）	正则提取飞书链接、文件附件、Kimi链接
build_graph.py	消息JSON	output/knowledge-graph/knowledge_graph.json	构建知识图谱（人物、文档、主题、关系）
write_obsidian.py	硬编码内容	output/obsidian-vault/ 目录	生成 Obsidian 知识库（含双向链接）
write_report.py	硬编码内容	output/reports/花园世界全量汇总.md	生成全量汇总报告
gen_visual.py	knowledge_graph.json	output/knowledge-graph/ HTML+Mermaid	生成可视化知识图谱
daily_feishu_collector.py	dws CLI	feishu_links_YYYYMMDD.json	每日定时采集（增量）

---

钉钉消息为什么能拿到？

原理：通过 dws CLI（悟空工具）直接调用钉钉内部API。

dws CLI -> 钉钉内部 API -> 群聊消息（含发送者、时间、内容、文件ID）

• dws CLI 是公司内部工具，已经封装好了钉钉API的认证和调用
• 你只需要提供群组的 openConversationId 和时间范围
• 返回的消息内容是 JSON 格式，包含消息文本、发送者、时间戳等
• 文件附件可以通过 fileId 用 dws drive download 下载

不需要：申请钉钉开放平台应用、配置回调URL、处理webhook。

---

飞书文档为什么能拿到？

原理：lark-cli 使用你的飞书账号 OAuth 授权，以你的身份调用飞书 Open API。

你登录飞书 -> OAuth Token -> lark-cli -> /open-apis/docx/v1/documents/{id}/blocks -> 文档内容JSON

三个前提条件：

1. 你有飞书账号：公司飞书租户下的账号
2. 你有文档访问权限：文档对你可见（在群里分享过的文档，群成员通常都有权限）
3. lark-cli 授权成功：lark-cli auth login 一次即可，后续自动使用缓存的token

能读到什么：

• docx 类型文档：直接通过 doc_id 调 Block API 获取全部内容
• wiki 类型文档：需要先通过 wiki API 解析节点ID得到真实 doc_id，再调 Block API
• 文件附件（XLSX/PPT/PDF等）：通过 dws drive download 从钉钉侧下载

读不到什么：

• 你没有权限的文档（跟浏览器一样，没权限就是没权限）
• 已被删除的文档

---

复刻步骤（从零开始）

第一步：确认工具就绪

# 检查 dws CLI
dws --version
# 如果没有，找IT获取

# 检查 Node.js
node --version  # 需要 18+

# 检查 Python
python --version  # 需要 3.10+

# 安装 lark-cli
npm install -g @larksuite/cli

# 安装 Python 依赖
pip install beautifulsoup4 requests

第二步：授权 lark-cli

lark-cli config init
lark-cli auth login --domain docs,drive,wiki --recommend
# 浏览器会自动打开，登录你的飞书账号即可

第三步：获取群组ID

你需要知道要采集的钉钉群的 openConversationId。获取方式：

1. 在钉钉管理后台查看
2. 或者用 dws 命令列出你所在的群
3. 或者找之前已经获取过的同事要

第四步：拉取消息

修改 scripts/fetch_all.py 中的群组ID和时间范围，然后运行：

python scripts/fetch_all.py

这会生成 data/raw-messages/all_messages_combined.json，包含两个群的全部消息。

第五步：提取链接

python scripts/extract_links.py

输出统计信息：飞书链接数、文件附件数、Kimi链接数等。

第六步：构建知识图谱

python scripts/build_graph.py

生成 output/knowledge-graph/knowledge_graph.json，包含人物、文档、主题、关系的结构化数据。

第七步：生成可视化和知识库

# 知识图谱可视化
python scripts/gen_visual.py
# 输出：output/knowledge-graph/knowledge_graph.html（浏览器打开即可查看）

# Obsidian 知识库
python scripts/write_obsidian.py
# 输出：output/obsidian-vault/（用 Obsidian 打开此目录）

# 汇总报告
python scripts/write_report.py

第八步：设置定时采集（可选）

# Windows 定时任务，每天18:00执行
schtasks /create /tn "FeishuDocCollector" /tr "python D:\path\to\scripts\daily_feishu_collector.py" /sc daily /st 18:00

---

常见问题

Q: 需要申请飞书开放平台的App吗？

不需要。 lark-cli 用的是浏览器 OAuth 授权（你的个人身份），不需要创建企业自建应用。

Q: 需要申请钉钉开放平台的权限吗？

不需要。 dws CLI 是内部工具，已经封装好了认证。

Q: 飞书文档有4种域名，都能读吗？

都能读，只要你有权限。不同域名对应不同的飞书空间/租户，lark-cli 用你的账号登录后可以跨空间访问。

本项目涉及的4个飞书域：

域名	说明
dianchukeji.feishu.cn	公司飞书
fcnlycv6dd0w.feishu.cn	研究组飞书空间
ocnmca6f1o0p.feishu.cn	另一飞书空间
my.feishu.cn	个人飞书

Q: 消息太多拉不完怎么办？

分段拉取 + openMessageId 去重。见 fetch_all.py 中的分段策略。

Q: Token 过期了怎么办？

重新运行 lark-cli auth login --domain docs,drive,wiki --recommend，浏览器重新授权即可。

Q: wiki 链接和 docx 链接有什么区别？

docx 链接的ID就是文档ID，可以直接调API。wiki 链接的ID是知识库节点ID，需要先通过 wiki API 解析出真实的文档ID。

---

技术栈总结

层级	工具	获取方式	费用
钉钉消息采集	dws CLI	悟空(Wukong)自带，装悟空就有	免费
钉钉文件下载	dws drive	同上，dws 的子命令	免费
飞书文档读取	lark-cli	npm install -g @larksuite/cli	免费
数据处理	Python + BeautifulSoup	悟空自带Python，BS4需 pip install	免费
知识库管理	Obsidian	https://obsidian.md 下载	免费

总成本：0元，只需要你有飞书账号和钉钉群访问权限。

---

产出物展示

产出	路径	用途
知识图谱（交互式）	output/knowledge-graph/knowledge_graph.html	浏览器打开，查看人物、文档、主题关系
Obsidian 知识库	output/obsidian-vault/	用 Obsidian 打开，双向链接浏览
汇总报告	output/reports/花园世界全量汇总.md	一份完整的 Markdown 报告
原始文档	output/feishu-docs/	155篇飞书文档的本地备份
下载文件	dc_files/	PPT/PDF/XLSX 等附件

---

项目数据一览

指标	数量
采集群组	2个（dc战略问题研究院 + 创新组）
消息总数	377条
飞书文档	155篇
文件附件	19个
活跃人员	28位
时间跨度	2026-05-01 ~ 2026-06-03
知识主题	7个核心主题