dingtalk-knowledge-search

name	dingtalk-knowledge-search
description	钉钉知识库搜索与读取。用于在钉钉沉淀知识里快速查资料、理解项目背景、梳理团队/部门信息、回答制度问题、整理新人入门材料、读取文档正文、导出 Markdown、下载文件，并可带图片和 diagram。

用法

cd <the_skill_dir_path>/scripts
python3 cli.py config check
python3 cli.py search "关键词1 关键词2 关键词3"
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<node_id>"
python3 cli.py read <node_id>

配置

先运行配置校验：

python3 cli.py config check

需要这些配置：

配置	用途	获取方式
DINGTALK_APP_KEY	调用钉钉开放平台 API	钉钉开放平台 -> 应用管理 -> 企业内部应用 -> 凭证与基础信息
DINGTALK_APP_SECRET	获取 API token	同上，应用凭证信息中查看
DINGTALK_MY_USER_ID	当前操作者身份	管理后台 -> 通讯录 -> 成员管理 -> 点击成员查看 userId
DINGTALK_MY_OPERATOR_ID	文档 API 的 operatorId/unionId	有 DINGTALK_MY_USER_ID 后可自动转换

缺少 DINGTALK_MY_OPERATOR_ID 时执行：

python3 cli.py config to-unionid

得到什么

• search：返回匹配文档列表；可用 --limit <n> 控制数量
• read：返回 Markdown；长内容会写到文件并返回路径；非 ALIDOC 文件会下载原文件
• PDF 转文本：read <pdf_node_or_url> --mode pdf2text 会先下载 PDF，再用系统 pdftotext -layout 输出 .txt；如果系统没有 pdftotext，会提示安装 poppler-utils，并退回返回 PDF 路径
• 默认输出：写到 skill workspace 下的 .skills-workspace/dingtalk-knowledge-search/outputs/
• 项目沉淀：用 --output-dir "$PWD/dingtalk-docs" --output-path 把结果写到当前项目
• 输出缓存：下载/转换结果会在用户级缓存目录保留一份，远端 modifiedTime 未变化时复用；默认用硬链接写入 --output-dir，用 --output-strategy copy 可复制隔离
• 图片本地化：用 --with img-local，图片会下载到 Markdown 同目录 .assets/<文档名>/
• 图片代理：用 --with img，节约本地空间，但依赖代理服务和原链接有效期
• diagram：用 --with diagram 一起导出

例子

python3 cli.py search "项目背景 年假 晋升" --limit 10
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<node_id>" --output-dir "$PWD/dingtalk-docs" --output-path
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<node_id>" --with img-local --with diagram --output-dir "$PWD/dingtalk-docs" --output-path
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<file_node_id>" --output-dir "$PWD/dingtalk-docs"
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<pdf_node_id>" --mode pdf2text --output-dir "$PWD/dingtalk-docs"
python3 cli.py read "https://alidocs.dingtalk.com/i/nodes/<pdf_node_id>" --mode pdf2text --output-dir "$PWD/dingtalk-docs" --output-strategy copy

缓存

• search 不缓存，每次直接查远端
• node、resolve-url、blocks 仍使用 SQLite API 缓存，受 --cache-ttl 影响
• 输出文件缓存不受 TTL 影响，使用远端 modifiedTime 判断是否复用
• 输出缓存默认位置：~/.dingtalk-skills/dingtalk-knowledge-search/output-cache/
• 默认 --output-strategy link：把全局缓存硬链接到当前 --output-dir，节省空间；编辑任一硬链接文件会影响同一份内容
• --output-strategy copy：复制到当前 --output-dir，和全局缓存隔离
• python3 cli.py cache clear --namespace output --yes 会删除输出缓存记录和关联本地文件

登录

• 需要扫码时，命令会返回 loginRequired: true 和 screenshotPath
• 扫码后重新执行同一个命令