skills/breath57__dingtalk-skills
1
0
Fork 0
mirror of https://github.com/breath57/dingtalk-skills.git synced 2026-09-14 20:51:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(dingtalk-knowledge-search): 新增钉钉知识库搜索与读取技能

Browse Source 
- 搜索知识库、读取文档正文导出 Markdown
- 图片本地化/代理、diagram 导出
- 表格导出 CSV、文件下载、PDF 转文本
- 跨项目输出缓存、扫码登录
- 融入仓库：SKILL.md + scripts/cli.py + references/browser-login-state.md
- 更新 AGENTS.md / README.md / README_EN.md 技能列表与安装命令
- .gitignore 忽略运行时产物 .skills-workspace/ 与 dingtalk-docs/
This commit is contained in:
breath57
2026-06-26 19:35:16 +08:00
parent 9e778be829
commit 2d3ea3f68b
7 changed files with 3757 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/dingtalk-knowledge-search/SKILL.md
+75
View File
@@ -0,0 +1,75 @@
---
name: dingtalk-knowledge-search
description: 钉钉知识库搜索与读取。用于在钉钉沉淀知识里快速查资料、理解项目背景、梳理团队/部门信息、回答制度问题、整理新人入门材料、读取文档正文、导出 Markdown、下载文件，并可带图片和 diagram。
---
## 用法
```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`
- 扫码后重新执行同一个命令
.agents/skills/dingtalk-knowledge-search/references/browser-login-state.md
+57
View File
@@ -0,0 +1,57 @@
# DingTalk Login State
## Normal Flow
- Prefer API reads for normal documents.
- Use browser fallback only when `--with img-local`, `--with diagram`, or API `403 forbidden.accessDenied` requires rendered web content.
- The browser fallback first tries the saved `agent-browser` state.
- If DingTalk redirects to `login.dingtalk.com`, run `login` to open the page, wait until the QR image/canvas is rendered, capture the QR element as a screenshot under the current project's `.skills-workspace/dingtalk-knowledge-search/`, print the screenshot path, and exit immediately.
- Give the screenshot to the user to scan in DingTalk.
- After the user scans, run the same `login` command again. If the target DingTalk document opens and an iframe is loaded, the script saves `$HOME/.dingtalk-skills/dingtalk-knowledge-search/dingtalk-browser-state.json` and closes the login session.
- Subsequent reads use the saved state and return to background/headless operation.
## QR Screenshot Login
- The login screenshot is written as `.skills-workspace/dingtalk-knowledge-search/*-login-qr.png` in the current project by default.
- Set `DINGTALK_LOGIN_SCREENSHOT_DIR` to override the screenshot directory.
- The screenshot targets the QR element itself when possible, not the full login page.
- The `login` command prints JSON with `action: "scan_required"` and `screenshotPath` when a QR scan is needed.
- It must see both QR-login text and a rendered QR image/canvas/background before it captures the screenshot.
- The same `login` command prints `action: "authenticated"` after successful scan and state save.
- Login is considered usable only after the page URL is under `https://alidocs.dingtalk.com/` and the document iframe exists.
- No `xdotool`, desktop coordinate click, or headed browser interaction is required for the normal QR flow.
- Browser-backed reads that discover an expired/missing login state run the same QR screenshot flow and return JSON with `loginRequired: true` and `screenshotPath` instead of blocking for scan.
## Manual Recovery
Manual login flow:
```bash
python3 cli.py login "https://alidocs.dingtalk.com/i/nodes/<node_id>"
python3 cli.py login "https://alidocs.dingtalk.com/i/nodes/<node_id>"
```
The user scans the screenshot with DingTalk between those commands. After the document opens, the second `login` saves `$HOME/.dingtalk-skills/dingtalk-knowledge-search/dingtalk-browser-state.json` and closes the login session.
## Force Closing agent-browser
Normally close with:
```bash
python3 cli.py browser close
```
If `agent-browser` reports stale daemon/session behavior, force close only agent-browser-owned processes:
```bash
python3 cli.py browser close --force
```
Equivalent manual checks:
```bash
pgrep -af "agent-browser|/tmp/agent-browser-chrome-|chrome_crashpad_handler"
ss -ltnp
```
Avoid broad `pkill chrome`; it may kill the user's unrelated browser.
.agents/skills/dingtalk-knowledge-search/scripts/cli.py
+3534
View File
File diff suppressed because it is too large Load Diff
.gitignore
+6 -1
View File
@@ -11,4 +11,9 @@ docs/
# traffic dashboard — local only
traffic/
temp/
temp/
# skill runtime artifacts (dingtalk-knowledge-search outputs)
.skills-workspace/
dingtalk-docs/
AGENTS.md
+7
View File
@@ -55,6 +55,12 @@ dingtalk-skills/
│ │ └── dt_helper.sh
│ └── references/
│ └── api.md
├── dingtalk-knowledge-search/ # 钉钉知识库搜索与读取技能（Python）
│ ├── SKILL.md
│ ├── scripts/
│ │ └── cli.py
│ └── references/
│ └── browser-login-state.md
└── dingtalk-skill-creator/ # 技能创建流程工具
└── SKILL.md
```
@@ -72,6 +78,7 @@ dingtalk-skills/
| `dingtalk-contact` | `.agents/skills/dingtalk-contact/` | ✅ 可用 | 钉钉通讯录：按关键词搜索用户/部门、获取用户完整详情、部门树遍历、成员列表、身份转换、员工总数 |
| `dingtalk-ai-web-search` | `.agents/skills/dingtalk-ai-web-search/` | ✅ 可用 | 网页搜索与实时信息检索：查最新资讯/实时数据/技术文档，基于小宿AI智能搜索，支持时间过滤与 JSON 输出 |
| `dingtalk-calendar` | `.agents/skills/dingtalk-calendar/` | ✅ 可用 | 钉钉日程：主日历 CRUD、闲忙、视频会议、会议室忙闲与绑定、签到签退与链接、循环/订阅说明（见 SKILL） |
| `dingtalk-knowledge-search` | `.agents/skills/dingtalk-knowledge-search/` | ✅ 可用 | 钉钉知识库搜索与读取：搜索知识库、读取文档正文导出 Markdown、图片/diagram 本地化、表格导出 CSV、文件下载、PDF 转文本（依赖 Python 3） |
| `dingtalk-skill-creator` | `.agents/skills/dingtalk-skill-creator/` | ✅ 可用 | 标准化创建新钉钉技能的开发流程工具 |
| `skill-creator` | `.agents/skills/skill-creator/` | ✅ 可用 | 技能开发框架（由 anthropics/skills 提供） |
README.md
+42 -2
View File
@@ -37,6 +37,7 @@ Agent 每次执行任务都需要将技能文件装入上下文，**skill 文件
| [dingtalk-contact](#dingtalk-contact--钉钉通讯录) | ✅ 已上线 | 通讯录：搜索用户/部门、用户详情、部门树、成员列表 | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-contact) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-contact) |
| [dingtalk-ai-web-search](#dingtalk-ai-web-search--网页搜索) | ✅ 已上线 | 网页搜索：关键词搜索、时间过滤、JSON 输出 | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-ai-web-search) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-ai-web-search) |
| [dingtalk-calendar](#dingtalk-calendar--钉钉日程) | ✅ 已上线 | 日程：CRUD、闲忙、视频会议、会议室、签到签退 | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-calendar) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-calendar) |
| [dingtalk-knowledge-search](#dingtalk-knowledge-search--钉钉知识库搜索与读取) | ✅ 已上线 | 知识库搜索、文档读取导出 Markdown、图片/diagram、表格 CSV、文件下载、PDF 转文本 | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-knowledge-search) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-knowledge-search) |
| dingtalk-approval | 🗓️ 计划中 | 审批流程管理 | — |
| dingtalk-attendance | 🗓️ 计划中 | 考勤打卡管理 | — |
| dingtalk-meeting | 🗓️ 计划中 | 视频会议管理 | — |
@@ -71,13 +72,13 @@ npx skills add breath57/dingtalk-skills@dingtalk-document --agent hermes-agent -
**一键安装全部**：
```bash
npx skills add breath57/dingtalk-skills \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar dingtalk-knowledge-search
```
**一键安装全部（Hermes）**：
```bash
npx skills add breath57/dingtalk-skills \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar dingtalk-knowledge-search \
--agent hermes-agent -y
```
@@ -311,6 +312,39 @@ npx skills add breath57/dingtalk-skills@dingtalk-calendar --agent hermes-agent -
---
### dingtalk-knowledge-search — 钉钉知识库搜索与读取
🦞 [ClawHub · dingtalk-knowledge-search](https://clawhub.ai/breath57/dingtalk-knowledge-search)
**安装**
```bash
# 1. ClawHub
clawhub install breath57/dingtalk-knowledge-search
# 2. skills.sh（全通用方式，支持 Cursor / Claude / Copilot / 🦞 OpenClaw 等几乎所有 Agent）
npx skills add breath57/dingtalk-skills@dingtalk-knowledge-search
# 3. Hermes
npx skills add breath57/dingtalk-skills@dingtalk-knowledge-search --agent hermes-agent -y
```
| 能力 | 说明 |
|---|---|
| 知识库搜索 | 按关键词搜索知识库，返回匹配文档列表 |
| 读取文档正文 | 导出 Markdown；长内容写入文件并返回路径 |
| 文件下载 | PDF / Word / PPT / Excel / CSV / 图片 / ZIP 等原文件下载 |
| PDF 转文本 | `--mode pdf2text`，需系统 `pdftotext`（poppler-utils） |
| 表格导出 CSV | 钉钉表格 / AI 表格 / 多维表按 sheet 导出 |
| 图片本地化 | `--with img-local`，图片下载到 `.assets/` |
| 图片代理 | `--with img`，Markdown 使用代理链接，节省本地空间 |
| diagram 导出 | `--with diagram`，保留流程图 / 结构图源码 |
| 输出缓存 | 跨项目复用，按远端 modifiedTime 判断是否复用 |
| 扫码登录 | 需要确认身份时返回二维码截图路径，扫码后继续执行 |
> 示例："帮我了解一下 A 项目的背景，相关文档导出 Markdown 到当前项目" → Agent 搜索知识库、读取正文、本地化图片并写入目录。
---
## 项目结构
```
@@ -345,6 +379,12 @@ npx skills add breath57/dingtalk-skills@dingtalk-calendar --agent hermes-agent -
│ │ └── dt_helper.sh
│ └── references/
│ └── api.md
├── dingtalk-knowledge-search/
│ ├── SKILL.md
│ ├── scripts/
│ │ └── cli.py
│ └── references/
│ └── browser-login-state.md
└── dingtalk-skill-creator/
└── SKILL.md
```
README_EN.md
+36 -2
View File
@@ -37,6 +37,7 @@ Every task execution loads skill files into the agent's context window — **the
| [dingtalk-contact](#dingtalk-contact--dingtalk-directory) | ✅ Available | Directory: search users/departments, user details, department tree | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-contact) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-contact) |
| [dingtalk-ai-web-search](#dingtalk-ai-web-search--web-search) | ✅ Available | Web search: keyword search, time filter, JSON output | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-ai-web-search) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-ai-web-search) |
| [dingtalk-calendar](#dingtalk-calendar--calendar--schedule) | ✅ Available | Calendar: CRUD, free/busy, video meetings, rooms, sign-in/out | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-calendar) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-calendar) |
| [dingtalk-knowledge-search](#dingtalk-knowledge-search--knowledge-base-search--read) | ✅ Available | Knowledge base search, doc read to Markdown, images/diagrams, table CSV, file download, PDF→text | [🦞 ClawHub](https://clawhub.ai/breath57/dingtalk-knowledge-search) · [<img src="https://avatars.githubusercontent.com/u/108547162?s=200&v=4" height="16"> Skills.sh](https://skills.sh/breath57/dingtalk-skills/dingtalk-knowledge-search) |
| dingtalk-approval | 🗓️ Planned | Approval workflow management | — |
| dingtalk-attendance | 🗓️ Planned | Attendance & check-in management | — |
| dingtalk-meeting | 🗓️ Planned | Video meeting management | — |
@@ -71,13 +72,13 @@ npx skills add breath57/dingtalk-skills@dingtalk-document --agent hermes-agent -
**Install all skills at once**:
```bash
npx skills add breath57/dingtalk-skills \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar dingtalk-knowledge-search
```
**Install all skills at once (Hermes)**:
```bash
npx skills add breath57/dingtalk-skills \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar \
--skill dingtalk-document dingtalk-ai-table dingtalk-message dingtalk-todo dingtalk-contact dingtalk-ai-web-search dingtalk-calendar dingtalk-knowledge-search \
--agent hermes-agent -y
```
@@ -311,6 +312,39 @@ npx skills add breath57/dingtalk-skills@dingtalk-calendar --agent hermes-agent -
---
### dingtalk-knowledge-search — Knowledge Base Search & Read
🦞 [ClawHub · dingtalk-knowledge-search](https://clawhub.ai/breath57/dingtalk-knowledge-search)
**Install**
```bash
# 1. ClawHub
clawhub install breath57/dingtalk-knowledge-search
# 2. skills.sh (universal — works with Cursor / Claude / Copilot / 🦞 OpenClaw and almost any Agent)
npx skills add breath57/dingtalk-skills@dingtalk-knowledge-search
# 3. Hermes
npx skills add breath57/dingtalk-skills@dingtalk-knowledge-search --agent hermes-agent -y
```
| Capability | Description |
|---|---|
| Knowledge base search | Search by keywords, return matching document list |
| Read document body | Export to Markdown; long content written to a file and path returned |
| File download | Download PDF / Word / PPT / Excel / CSV / image / ZIP originals |
| PDF to text | `--mode pdf2text`, requires system `pdftotext` (poppler-utils) |
| Table export to CSV | DingTalk workbook / AI table sheets exported per-sheet |
| Image localization | `--with img-local`, images downloaded to `.assets/` |
| Image proxy | `--with img`, Markdown uses proxy links to save local space |
| Diagram export | `--with diagram`, keep flowchart / structure diagram sources |
| Output cache | Reuse across projects by remote modifiedTime |
| QR login | Returns a QR screenshot path when identity confirmation is needed; resume after scan |
> Example: "Get up to speed on Project A's background and export related docs to Markdown in the current project" → Agent searches the knowledge base, reads bodies, localizes images, and writes to the directory.
---
## License
MIT