---
name: dingtalk-knowledge-search
description: 钉钉业务知识搜索与读取操作。当用户需要搜索钉钉知识、按关键词查文档、读取钉钉文档正文、导出 Markdown、解析文档中的图片或 diagram 时使用。支持搜索、按 URL 或 nodeId 读取、图片代理、本地图片导出、diagram 提取、缓存管理；不负责创建、写入、删除文档或成员权限管理，这些属于 dingtalk-document。
---

# Skill: dingtalk-knowledge-search

## 能做什么

- 搜索钉钉知识库文档
- 按 URL 或 nodeId 读取文档内容
- 对 `xlsx`、`xls`、`csv`、`pdf`、`docx`、`doc`、`pptx`、`ppt` 等非 ALIDOC 文件，`read-url`/`read` 会下载原文件到输出目录
- 对 `.dlink/.dlnk` 快捷方式，`read-url` 会优先按同名搜索唯一 ALIDOC 目标并读取；未找到唯一目标时返回候选列表
- 导出 Markdown
- 解析文档里的图片和 diagram
- 管理图片代理和缓存
- 不负责创建、写入、删除文档或成员权限管理，这些属于 `dingtalk-document`

## 使用方式

先进入 skill 目录，后续命令都按这个相对路径执行：

```bash
cd <the_skill_dir_path>/scripts && python3 dingtalk_knowledge_cli.py --help
```

## 按任务校验配置（必须先做）

- 所有任务通用必需：`DINGTALK_APP_KEY`、`DINGTALK_APP_SECRET`、`DINGTALK_MY_USER_ID`
- 涉及任何文档/知识库 API 调用：必须有 `DINGTALK_MY_OPERATOR_ID`。若缺失，先用 `bash scripts/dt_helper.sh --to-unionid` 自动转换并写回。
- 搜索、读取、图片解析、diagram 提取：除上述配置外，无额外固定配置键。
- `workspaceId`、`nodeId`、`docKey` 属于任务参数，运行时从用户输入或 API 响应中获取。

规则：未通过本次任务配置校验前，不得进入 API 调用步骤。

凭证禁止在输出中完整打印，确认时仅显示前 4 位 + `****`。

校验命令：

```bash
python3 scripts/dingtalk_knowledge_cli.py config-check
```

### 所需配置

| 配置键 | 必填 | 说明 | 如何获取 |
| --- | --- | --- | --- |
| `DINGTALK_APP_KEY` | 是 | 应用 AppKey | 钉钉开放平台 -> 应用管理 -> 凭证信息 |
| `DINGTALK_APP_SECRET` | 是 | 应用 AppSecret | 钉钉开放平台 -> 应用管理 -> 凭证信息 |
| `DINGTALK_MY_USER_ID` | 是 | 当前用户的企业员工 ID（userId） | 管理后台 -> 通讯录 -> 成员管理 -> 点击姓名查看 |
| `DINGTALK_MY_OPERATOR_ID` | 是 | 当前用户的 unionId（operatorId） | 首次由 `bash scripts/dt_helper.sh --to-unionid` 自动转换并写入 |

### 身份标识说明

| 标识 | 说明 |
| --- | --- |
| `userId`（= `staffId`） | 企业内部员工 ID，可通过管理后台 -> 通讯录 -> 成员管理 -> 点击姓名查看 |
| `unionId` | 跨企业/跨应用唯一标识，可通过 `bash scripts/dt_helper.sh --to-unionid <userId>` 获取 |

## 常用命令

搜索文档：

```bash
python3 dingtalk_knowledge_cli.py search "CRC Copilot Bot" --limit 10
```

读取文档：

```bash
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>"
python3 dingtalk_knowledge_cli.py read <node_id>
```

读取非 ALIDOC 文件时会自动下载原文件，优先使用官方服务端 API：`根据 dentryUuid 获取 spaceId` -> `获取文件下载信息`，失败时才回退浏览器下载：

```bash
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<xlsx_or_pdf_node_id>" --output-dir "$PWD/dingtalk-docs"
```

默认输出会落到当前执行目录下的 `.skills-workspace/dingtalk-knowledge-search/outputs/`。也可显式导出到当前项目或用户指定目录：

```bash
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>" --output-dir "$PWD/dingtalk-docs" --output-path
```

读取文档并带图片或 diagram：

```bash
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>" --with img --output-dir "$PWD/dingtalk-docs" --output-path
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>" --with img-local --output-dir "$PWD/dingtalk-docs"
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>" --with diagram --output-dir "$PWD/dingtalk-docs" --output-path
python3 dingtalk_knowledge_cli.py read-url "https://alidocs.dingtalk.com/i/nodes/<node_id>" --with img-local --with diagram --output-dir "$PWD/dingtalk-docs"
```

必要时手动刷新网页登录态（通常无需主动执行；`--with img-local`、diagram、API 403 后的浏览器回退读取会自动触发）：

```bash
python3 dingtalk_knowledge_cli.py browser-login "https://alidocs.dingtalk.com/i/nodes/<node_id>"
```

如果登录态失效，脚本会自动打开有头浏览器恢复会话。钉钉可能弹出 Chrome 原生权限框：`login.dingtalk.com wants to Access other apps and services on this device`。如果本机安装了 `xdotool`，脚本会尝试自动点击 `Allow`；如果没有安装，也不会报错，用户在弹出的浏览器里手动点击 `Allow` 即可继续。之后脚本会自动点击页面里识别到的身份入口（如 `姓名@组织`、`Click the profile photo`、`You will log in with the account below`）。如果出现二维码或额外确认，用户处理一次即可。成功进入文档后脚本会保存 state 并关闭有头浏览器，后续读取回到无头/后台模式。

缓存管理：

```bash
python3 dingtalk_knowledge_cli.py cache stats
python3 dingtalk_knowledge_cli.py cache clear
python3 dingtalk_knowledge_cli.py cache clear --namespace search
```

代理服务：

```bash
python3 dingtalk_proxy.py start
python3 dingtalk_proxy.py status
python3 dingtalk_proxy.py stop
python3 dingtalk_proxy.py cleanup --retention-days 30
```

## 常用参数

- `--with img`：输出代理图片 URL
- `--with img-origin`：输出原始图片 URL
- `--with img-local`：下载图片到 Markdown 同目录的 `.assets/<文档名>/`，并把 Markdown 图片路径改为相对路径
- `--with diagram`：提取 diagram 内容
- `--output-dir <dir>`：指定 Markdown 输出目录，推荐显式传入当前项目下的目录，例如 `$PWD/dingtalk-docs`
- `--output-path`：强制输出为 Markdown 文件并返回文件路径；它不是目录参数

## 配置与状态

- 配置文件：`$HOME/.dingtalk-skills/config`
- 状态目录：`$HOME/.dingtalk-skills/dingtalk-knowledge-search/`
- 浏览器状态：`$HOME/.dingtalk-skills/dingtalk-knowledge-search/dingtalk-browser-state.json`
- 默认输出目录：当前执行目录下的 `.skills-workspace/dingtalk-knowledge-search/outputs/`
- `--with img-local` 图片目录：输出 Markdown 所在目录下的 `.assets/<文档名>/`
- 非 ALIDOC 文件下载目录：`--output-dir` 指定目录，未指定时使用默认输出目录
- 非 ALIDOC 文件下载链路：优先官方 API，返回结果里的 `method` 为 `official-api`；若官方 API 不可用，会回退浏览器下载，`method` 为 `browser-fallback`。

未指定 `--output-dir` 时，长文档默认输出到当前执行目录下的 `.skills-workspace/dingtalk-knowledge-search/outputs/`，不会再把 Markdown 输出到全局状态目录。需要长期保留或本地浏览图片时，仍建议指定项目内目录。

如果需要图片、diagram 或网页登录态能力，确保本地已具备可用登录态。

## 浏览器登录态说明

- 普通正文优先走 DingTalk API。
- `--with img-local`、`--with diagram`、以及部分 API 返回 `403 forbidden.accessDenied` 的文档，会走浏览器回退链路。
- 浏览器回退链路依赖 `agent-browser`。`xdotool` 是可选增强能力，不是硬依赖；未安装时用户手动点击 Chrome 顶部 `Allow` 即可。
- `--with img` 代理图片只保存短链到原始 URL 的映射，不缓存图片二进制；每次预览图片都会实时转发请求，避免缓存到过期或无权限占位图。
- 登录页会注入右上角操作提示，解释为什么需要登录、何时点 `Allow`、何时扫码/确认；登录成功保存状态后会自动关闭浏览器。
- `xdotool` 通过 X11 `XTEST` 扩展模拟真实鼠标/键盘事件，能自动点击 Chrome 顶部权限气泡；`agent-browser click` 只能稳定操作网页 DOM/可访问性元素，不能点击浏览器原生 UI。没有 `xdotool` 时流程仍可用，只是该原生权限气泡需要用户手动点一次。
- 如果页面出现二维码登录或需要人工确认，使用 `browser-login` 让用户在有头浏览器里操作一次，成功进入文档后会保存 state，后续读取会复用。
- `.dlink` 节点不是正文文档。遇到 `.dlink` 时先在浏览器里打开并复制最终跳转后的真实文档 URL，再用 `read-url` 读取。
- agent-browser 状态和强制关闭说明见 `reference/browser-login-state.md`。