# LarkReader 使用说明

LarkReader 是一款把「飞书知识库」下载到本地的工具：扫描目录结构 → 勾选需要的节点 → 下载成
Markdown / XLSX / NDJSON / 原始附件，之后可离线阅读、长期留档。文档只在本地读写，正文与
图片下载到你的磁盘，不依赖在线状态。

> **适用平台**：Windows 10+ / macOS 11+ / Ubuntu 20.04+（x86_64 / arm64）。
> 当前发布的安装包暂为 **Windows（x64）**；macOS / Linux 用户可到
> [项目仓库](https://github.com/LPK3215/LarkReader) 参照 README「快速开始」从源码自行构建。

---

## 1. 界面总览

启动后进入主窗口，左侧竖排图标依次是：

![LarkReader 主窗口：左侧功能导航，中间为工作台导出入口](./screenshots/workspace-export-empty.png)

| 图标入口 | 名称 | 作用 |
|---|---|---|
| 工作台 | 工作台 | 贴链接 → 勾选 → 下载，一条主线 |
| 任务历史 | 任务历史 | 查看 24 小时内的下载记录、打开产物目录、删除记录 |
| 本地阅读 | 本地阅读 | 把已下载的知识库渲染成可离线浏览的目录树 + 文档阅读 |
| 飞书终端 | 飞书终端 | 手动体检环境、登录/切换账号、退出登录 |
| 运行日志 | 运行日志 | 回看下载/登录等关键事件日志 |
| 设置 | 设置 | 输出位置、下载图片、并发数、检查更新 |

窗口底部还有一个全局任务条：下载进行中时无论切到哪个页面都能看到进度、剩余时间，并可随时取消。

---

## 2. 首次启动：三步引导

> **运行前提**：本机需已安装 [Node.js 22+](https://nodejs.org/)。LarkReader 通过官方
> `@larksuite/cli` 读写飞书数据，cli 本体会由应用在体检步骤自动安装，但它依赖 Node.js；
> 未安装时「环境体检」会失败并给出提示，装好 Node 后点重新检测即可。

第一次运行会走全屏引导，按顺序完成：

1. **环境体检**：自动检查/安装固定版本的 `@larksuite/cli`，全绿后进入下一步。
   安装支持**自动 / 手动**两种方式：自动安装显示进度，失败会自动重试；也可切到手动方式
   复制命令在自己的终端执行后回来重新检测。
2. **应用配置**：需要绑定一个「飞书自建应用」。推荐点「一键自动创建并打开浏览器」——
   应用会后台跑创建向导并自动把浏览器弹到飞书开放平台，你在页面里完成创建即可；
   完成后面板自动重新检测。也可用下方“手动方式”在自己的终端粘贴命令操作（只做一次，长期有效）。
3. **登录 + 选择默认输出目录**：使用飞书账号设备码登录（设备码与授权链接均可一键复制）；
   选择将来下载文件存放的默认目录。

> 提示：右上角胶囊图标会显示环境健康状态（如“就绪/有告警”），点它可进入「飞书终端」查看详情。
> 引导完成后不会再次自动弹出；想重新走一遍，进「设置 → 新手引导 → 重新运行引导」。

---

## 3. 下载知识库（工作台主线）

### 3.1 粘贴链接并选择扫描模式

在「工作台」粘贴一条**知识库内的页面链接**（形如 `https://xxx.feishu.cn/wiki/<token>`），
然后选择扫描模式：

- **展开整个知识库（含兄弟节点）**（FullSpace，**默认**）
  无论贴的是哪种链接，都自动列出该知识库空间下的全部顶层节点并递归展开，
  一次拿到整库；你贴的那个节点会按真实层级出现在树中。
  展开只发生在顶层一次，之后与 Auto 的递归完全相同，不用担心嵌套混乱。
- **仅导出本节点及子树**（Auto）
  适合目标 URL 本身是一个带子文档的目录/父文档、且明确只要它这一支时：只导出它及后代。
  想精确控制导出范围时手动切到这一项。

如果选错了模式也没关系：扫描只读目录树，不下载任何正文、不写磁盘，可以随时“换一个”重新扫。

### 3.2 勾选节点

扫描后左侧出现节点树（展开前两层），可：

- 勾选/取消任意节点；勾选父节点会自动带上全部后代
- 全选/取消全选
- 右侧实时显示将导出的**文档/表格/多维表格/附件**数量

### 3.3 开始下载

右侧栏确认输出目录与选项后点「开始下载」：

- 目录默认存在你设置里选择的目录下，每次按知识库名新建子目录，同名不会互相覆盖
- 下载期间树上的节点会逐个打勾/打叉，右侧是阶段进度条与成功/失败计数
- 阶段顺序：排队 → 检查输出目录 → 扫描知识库 → 导出文档 → 导出表格 →
  导出多维表格 → 下载附件 → 收尾整理
- 失败不弹窗、不中断，只会累计在计数里；想要中途停下点「取消任务」

下载完成后右侧变成结果卡：显示成功/部分/失败/跳过统计与产物目录，可点「打开目录」查看，
或点「重新选择」回到勾选状态。点「查看异常明细」能看到失败/跳过原因。

### 3.4 产物长什么样

在产物根目录下，下载结果按这些规则组织：

| 内容 | 落盘格式 |
|---|---|
| 飞书文档 | `.md` 正文 + 图片就近存到 `<标题>_images/`，正文里是相对路径，可离线渲染 |
| 电子表格 | `.xlsx` |
| 多维表格 | 每张表一个 `.ndjson`，附同名 `.manifest.json` 元数据 |
| 普通文件附件（zip/pdf/docx 等） | 按原始字节原样保存，保留原名与扩展名 |

- 文件按“目录内顺序”加 `00_ 01_ …` 编号前缀，方便保持阅读顺序
- 目录/文件同名会自动追加 `(2)` 区分，不会互相覆盖
- 标题里的 `\ / : * ? " < > |` 等特殊字符会清洗成 `_`

---

## 4. 本地阅读（离线看文档）

把导出的目录变成阅读器：

1. 进入「本地阅读」，选择来源：
   - **已有导出**：最近一次任务产物，或 24 小时内任务历史里的产物（可点历史行的“应用内阅读”直达并自动定位第一篇文档）
   - 点「选择其他文件夹」手动指定任意已导出目录
2. 左侧是目录树（懒加载、目录优先排序），点任意文件在右侧打开
3. 预览能力：`.md` 渲染正文（图片内联）；csv / json / xml / log / txt 等文本直接看内容；png / jpg / svg 等看图；pdf 内嵌；其余格式一键用系统默认程序打开
4. 外部 http(s) 链接点击后交给系统浏览器；工具栏可“打开所在目录”“更换阅读源”

---

## 5. 任务历史

最近 24 小时、最多 100 条的下载记录都留在这里：

- 查看成功/失败汇总与异常明细
- **打开产物目录**、**在应用内阅读**（直达本地阅读并自动打开第一篇）
- 删除单条记录（不影响已落盘的文件）
- 刷新按钮同步最新状态

---

## 6. 运行日志

自动按天把关键事件（下载开始/逐项结果/汇总、登录登出、设置变更）写入本地日志文件：

- 顶部按日期切换文件；默认跟随最新
- 支持关键字过滤与自动刷新；停在底部时会自动滚到最新
- 「打开日志目录」可到文件管理器里查看原始 `.log`

---

## 7. 设置

| 项 | 说明 |
|---|---|
| 默认输出目录 | 每次导出的根目录；切换后立即做“可写性 + 可用空间”预检 |
| 下载文档中的图片 | 关闭后只保留 Markdown 文本与原始图片链接 |
| 图片并发下载数 | 1–32，网络较差时调低更稳 |
| 软件更新 | 显示当前版本；点「检查更新」拉取 GitHub Releases 的新版本并下载安装 |
| 新手引导 | 点「重新运行引导」可再次走一遍首次启动的三步引导 |

---

## 8. 软件更新

- 每次启动应用会**静默检查一次**新版本：发现新版才提示一次（指向「设置 → 软件更新」），不会反复打扰。
- 有新版时在设置页点「下载并安装 vX」即可自动完成：Windows 自动弹安装器并重启，
  macOS / Linux 安装完成后自动重启生效。
- 更新包下载地址与签名校验都在应用内置配置里，更新来源固定为项目 GitHub Releases。

> 说明：如果一直显示“已是最新”，说明当前版本不低于线上最新版，或线上版本尚未发布正式版。

---

## 9. 常见问题

| 问题 | 说明 / 处理 |
|---|---|
| 提示未登录/Token 失效 | 去「飞书终端」重新登录（浏览器授权一次） |
| 扫描只看到 1 个节点（入口页） | 该页面在目录树中没有子文档（旁边的节点是它的兄弟）；改用「展开整个知识库」模式重扫 |
| 某些节点“跳过” | 飞书里不支持的节点类型，导出已跳过，不视为失败 |
| 附件/特殊资源失败 | 在结果卡或历史记录里看具体原因，多为临时网络/权限，可单独重试 |
| 下载后图片显示不出来 | 请确认导出时勾选了“下载文档中的图片”，并用产物目录旁的 `_images` 目录一起移动 |
| macOS 首次打不开 | 未签名应用需右键 → 打开 → 在系统设置里允许（仅影响跨机器分发的版本） |
| Windows 首次运行有 SmartScreen 提示 | 点“仍要运行”即可（未购买商业代码签名证书的预期现象） |
| 想换电脑/备份 | 直接把导出的产物目录拷走即可；登录态与导出目录配置在本地配置目录，不随文件目录迁移 |

---

## 10. 边界与安全说明

- 本工具通过固定版本 `@larksuite/cli` 访问飞书，凭据托管在本地 lark-cli，不经过任何第三方服务器。
- 下载内容只写入你选择的本地目录；日志同样只保存在本机。
- 导出的 `.md` 引用的是本地相对路径图片，整个产物目录移动后依旧能离线渲染。