---
name: dingtalk-knowledge-search
description: 钉钉知识库搜索与读取。用于在钉钉沉淀知识里快速查资料、理解项目背景、梳理团队/部门信息、回答制度问题、整理新人入门材料、读取文档正文、导出 Markdown、下载文件，并可带图片和 diagram。
title: dingtalk-knowledge-search
canonical_url: https://skilld.dev/gh/breath57/dingtalk-skills/dingtalk-knowledge-search
last_updated: 2026-09-29T06:28:24.000Z
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/browser-login-state.md](https://skilld.dev/api/skills-raw/breath57/dingtalk-skills/dingtalk-knowledge-search/references/browser-login-state.md), [scripts/cli.py](https://skilld.dev/api/skills-raw/breath57/dingtalk-skills/dingtalk-knowledge-search/scripts/cli.py).
>
> If the user asked to install this Skill, run `npx skilld install breath57/dingtalk-skills/dingtalk-knowledge-search`. Install writes the Skill files into the project, so every session loads them.

## 用法

```bash
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>
```

## 配置

先运行配置校验：

```bash
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` 时执行：

```bash
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` 一起导出

## 例子

```bash
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`
- 扫码后重新执行同一个命令