Mr-SYGao/dsh-feishu-reader

🚢 dsh-feishu-reader

读取飞书文档 — 文字 / 表格 / 图片，一键转 Markdown 喂给 AI

Read Feishu (Lark) docs — text, tables & images — as Markdown for your AI

version
CI
license
node
tests
PRs

✨ 特性 / Features

| | 能力 | 说明 |
| --- | --- | --- |
| 📝 | 文字读取 | 云文档 / 知识库 / 电子表格 / 多维表格，保留标题、列表、代码块 |
| 🧾 | 表格还原 | 表格转成真正的 Markdown 表格，合并单元格内容不丢 |
| 🖼️ | 图片下载 | 文档里的图片下载到本地，AI 用视觉工具读图 |
| 🎨 | 行内格式 | 加粗、 代码 、链接 保留 |
| 🔐 | 安全 | 凭证不落命令行、不硬编码 |
| ⚙️ | 设置界面 | 设置里一张卡片，点点就配好 |

🖼️ 效果预览 / Preview

🚀 安装

dsh plugin --profile desktop add dsh-feishu-reader

自动注册启动加载，重启 DSH 即生效；以后更新再跑一次同一条命令。

⚙️ 配置飞书（必需！）

⚠️ 不配置就无法使用。 这个插件通过「飞书开放平台」的接口读文档，需要你自己的飞书应用凭证。

1. 创建飞书自建应用

打开 飞书开放平台 → 创建企业自建应用 → 在「凭证与基础信息」拿到：

- App ID（cli_ 开头）
- App Secret

2. 开通权限（应用 → 权限管理 → 开通并发布）

| 权限 | 用途 |
| --- | --- |
| docx:document:readonly | 读取云文档 |
| wiki:wiki:readonly | 读取知识库 |
| sheets:spreadsheet:readonly | 读取电子表格 |
| bitable:app:readonly | 读取多维表格 |
| drive:drive:readonly | 下载文档内图片 |

3. 授权文档给应用

- 云文档 / 表格：把应用加为文档协作者
- 知识库：把应用加入知识库成员

4. 填入凭证

打开 设置 → 插件 → 插件配置 → 飞书，填 App ID / App Secret，点「保存凭证」。

也可以让 AI 调用 feishu_configure(app_id, app_secret) 配置。

🎯 开始使用

把飞书文档链接发给 AI 即可（/docx/、/wiki/、/sheets/、/base/ 都支持），AI 会读出全文、表格和图片。

❓ 常见问题 / FAQ

图片下载失败？

检查应用是否开通 drive:drive:readonly 并发布，且文档已分享给应用。

报「缺少飞书凭证」？

按上方配置飞书完成 1-4 步；或调用时直接传 app_id / app_secret。

插件重启后会不会没？

用 dsh plugin add 安装（写进 profile 的 bundles）→ 重启自动加载，不会没；会话里临时加载的才会没。

合并单元格显示重复内容？

Markdown 无法表达合并，插件把主单元格内容复制到覆盖位置，保证信息不丢（属正常）。

🧠 工作原理 / How It Works

1. AI 调用 feishu_read(url) → Host 解析链接类型与文档 token
2. 引擎（lib/script.js）通过 stdin 接收凭证，调飞书 Open API
3. 文字经 blocks 接口转结构化 Markdown（表格网格重建、行内格式保留）
4. 图片下载到本地临时目录，AI 再用视觉工具读图

🛠️ 开发 / Development

npm run test                   # 单元测试（node --test）
npm run check                  # 语法检查
npm run build:dynamic          # 从 lib/ 重新生成 host.js / client.js
node scripts/verify-client.mjs # 验证 client bundle 的 __ModuleLoader__ 注册协议
node scripts/verify-boot.mjs   # 验证 profile bundle 层可被 DSH boot 解析（本机路径）

单一来源：引擎逻辑只在 lib/script.js，动态版由构建脚本生成。

📄 License

MIT · Made with 🚢 for the DSH / Feishu community