飞书文档 · 本地阅读与导出工具
基于 Tauri 2 + Rust + Vue 3 的桌面应用。知识库递归导出，纯本地运行、数据不出机。
LarkReader 解决一个具体问题：把飞书知识库变成你硬盘上可直接阅读、离线可用的文件。
- 导出：递归遍历知识库，Doc → Markdown（图片本地化）、Sheet → XLSX、Bitable → NDJSON、file 附件 → 原样字节，整棵目录树按飞书层级与排序落盘；
- 阅读：内置「本地阅读」页，直接浏览已导出的 Markdown 与图片，不依赖网络和飞书登录；
- 边界：纯本地工具，无自建服务端、无遥测。凭据由官方
lark-cli在本机托管，LarkReader 不保存飞书密码或 token。
完整的功能、接口、架构、验证状态和后续边界统一记录在 后端功能与维护手册（唯一主文档，代码实现始终是最终依据）。
当知识库内容多、目录深、要在网络不稳定的环境下翻阅已读资料时，LarkReader 可以帮你把内容备份到本地、用更顺手的方式阅读。详细示例与典型场景图见 docs/use-cases.md。
已用一个真实的飞书知识库做过端到端验证：docs/e2e-download-case/ 是那次导出的完整产物，8 个顶层节点、38 项成功 / 0 失败 / 0 跳过，覆盖 docx 正文、Sheet、Bitable、文件附件四类节点，目录层级与飞书一致。
| 能力 | 说明 |
|---|---|
| 🔐 环境与认证 | 自动检测 Node.js / lark-cli / 应用配置 / 登录状态（并行检测，区分 5 种异常）；固定安装 @larksuite/cli@1.0.93，支持自动 / 手动双方式安装，自动失败重试 3 次并写入日志；设备码登录，设备码与授权链接可一键复制，配置向导自动弹浏览器；首次使用自动进入引导，设置页可重新运行引导 |
| 📄 单文档导出 | 接受 Wiki URL 或节点 token；Markdown 正文 + 图片并发下载（1–32 并发）并本地化 URL；同名自动 (2)(3) 编号不覆盖；事务式落盘，失败不留半截文件 |
| 🌲 Wiki 递归导出 | 保留目录层级与飞书排序；选文件夹自动含全部后代；循环 / 深度 ≤ 64 层 / 节点 ≤ 10,000 三重保护；同名知识库原子建目录不互覆 |
| 📊 表格与数据库 | Sheet → XLSX；Bitable 每张数据表 → NDJSON + .manifest.json 元数据（base_token / table_id / rev / 记录统计） |
| 📎 文件附件 | Wiki 页面挂载的 file 节点（zip / pdf / docx 等）按原始字节下载，文件名 = 位置前缀 + 原标题，字节数与上传一致 |
| 🧭 后台任务 | 任务立即返回 ID 后台执行；8 阶段进度（总数 / 完成数 / 当前标题 / 预计剩余）；协作式取消并返回部分结果；历史持久化（24 小时 / ≤ 100 条） |
| 📚 本地阅读 | 新增 Reader 页：浏览导出目录、渲染 Markdown 与图片（data URL 内联），离线可用 |
| 🔄 应用内更新 | 设置页一键「检查更新」；下载进度可见；公钥签名校验；Windows 自动安装并重启，macOS/Linux 安装后自动 relaunch |
| 🧱 可靠性 | 结构化错误协议（code / message / retryable）、输出目录预检（可写性 + 磁盘空间）、设置临时文件 / 备份 / 回滚、临时故障指数退避重试、运行日志页 |
前后端通过 Tauri IPC 通信：27 个命令，入参 camelCase / 出参 snake_case，业务错误统一走 AppError{code, message, retryable}，模型以 src-tauri/src/models.rs 与 src/api/types.ts 为准（改一侧必须同步另一侧）。
| 层 | 技术 |
|---|---|
| 桌面框架 | Tauri 2 |
| 后端 | Rust stable（tokio / reqwest / pulldown-cmark / rayon / thiserror / tracing） |
| 前端 | Vue 3.5 + TypeScript ~6.0 + Vite 8 |
| 状态与 UI | Pinia 4 + Naive UI + Vue Router |
| 内容源 | @larksuite/cli 固定 1.0.93（子进程调用，凭据托管） |
| CI/发布 | GitHub Actions 三平台（Windows / macOS / Linux）出包，v* tag 触发；完整手册见 docs/release-and-update.md |
LarkReader/
├── src/ # 前端（Vue 3 + TS，19 .vue + 19 .ts，约 7.8k 行）
│ ├── api/ # IPC 封装与类型契约（8 模块，types.ts 为唯一类型源）
│ ├── components/ # 业务组件（11 个，含 layout/ 布局组件）
│ ├── composables/ # 组合式函数（useTaskProgress / useMessage）
│ ├── stores/ # Pinia 状态（auth / task / settings / history / onboarding）
│ ├── views/ # 页面（Workspace / Reader / History / Logs / Terminal / Settings / Onboarding）
│ └── styles/ # 主题与组件样式
├── src-tauri/ # Rust 后端（Tauri 2，12 模块 / 约 5.0k 行）
│ ├── src/ # commands / env / lark / extract / wiki / reader / markdown
│ │ # models / error / logger / lib / main
│ ├── tests/ # 集成测试 5 套件（真实下载类需登录环境）
│ └── Cargo.toml
├── docs/
│ ├── assets/ # README 可视化资产（SVG，由脚本生成）
│ ├── scripts/ # SVG 生成脚本（Python，见 docs/scripts/README.md）
│ ├── e2e-download-case/ # E2E 测试库全量下载稳定快照（42 文件 / 18 种扩展名）
│ ├── e2e-fixtures/ # 测试库原始素材与生成脚本 gen_assets.py
│ ├── BACKEND.md # 后端功能与维护手册（唯一主文档）
│ ├── USER_GUIDE.md # 用户指南（面向最终用户：引导/下载/阅读/更新）
│ ├── manual-checklist.md # 发布后人工验收清单（逐项过功能）
│ ├── release-and-update.md # 构建 · 发版 · 应用内更新完整手册（环境、打包、签名密钥、CI、问题排查）
│ ├── FEISHU_AUTH.md # 飞书登录与应用权限说明
│ └── LOGIN_ISSUE_20260905.md # 登录问题排查记录
├── scripts/ # 仓库操作脚本（Node）：verify / clean-e2e / release
└── .github/workflows/ # publish.yml：三平台发布流水线
普通用户（推荐）：直接下载安装包（Windows MSI / macOS DMG / Linux AppImage、deb），跟随首次引导三步完成配置即可，日常操作见用户指南。 唯一前提：本机已安装 Node.js 22+（官方 lark-cli 依赖它，cli 本体由应用自动安装）。
开发者（从源码运行/构建）：Node.js 22+（包管理器统一为 npm）+ Rust stable（建议 rustup 安装）。
npm install
npm run tauri dev # 带 Rust 后端的桌面开发窗口首次启动会引导完成三步：
- 环境体检：自动安装固定版
@larksuite/cli@1.0.93（也可切手动方式复制命令自行安装）； - 应用配置：
config init --new创建向导自动弹出浏览器，全程无需手动输入（详见 FEISHU_AUTH.md）； - 登录：设备码登录，设备码与授权链接可一键复制，
ready/needs_refresh均视为有效登录态。
常用命令：
npm run verify # 发布门禁：fmt / clippy / 单测 / 前端构建，任一失败即停
npm run clean:e2e # 清空 E2E 下载回归输出目录（跑批前必做）
npm run release -- <版本> # 一键发版：门禁 → tag → 推送 → CI 三平台出包
npm run dev仅启动前端（Vite）。完整功能需要真实 Rust 后端，请使用npm run tauri dev。
| 文档 | 内容 |
|---|---|
| docs/USER_GUIDE.md | 使用说明（面向最终用户）：界面总览、首次引导、知识库下载/扫描模式、本地阅读、历史、日志、设置、更新、FAQ |
| docs/manual-checklist.md | 人工验收清单：安装发布版后逐项过功能，全绿再对外宣传 |
| docs/BACKEND.md | 后端功能、27 个 Tauri 命令接口、数据结构、模块职责、验证状态（唯一主文档） |
| docs/release-and-update.md | 构建 · 发布 · 应用内更新完整手册（环境、本地打包、签名密钥、GitHub Actions 三平台出包、问题排查） | | docs/FEISHU_AUTH.md | 飞书自建应用创建、权限清单、登录链路说明 | | docs/e2e-download-case/ | E2E 测试库全量下载产物快照，可离线查看导出结构与命名规则（线上原地址） | | docs/scripts/README.md | 本仓库可视化资产的生成脚本使用说明 | | scripts/README.md | 仓库常用操作脚本说明 |
工程基线（本机可重复验证）：
cargo fmt --all -- --check 通过
cargo clippy --all-targets -- -D warnings 通过
cargo test --lib 26 项通过
npm run build 通过
E2E 真实下载实测（2026-09-05，真实飞书账号，测试库可反复复现）：
- 实测大型知识库（A）：22 个顶层节点、143 篇文档、多级目录全量下载与分粒度下载；
- E2E 测试库 8 个顶层节点：38 项成功 / 0 失败 / 0 跳过，产物 42 文件、18 种扩展名、18 个附件字节级一致（详见 docs/e2e-download-case/README.md，线上原地址）；
- 扫描模式覆盖：docs/scan-mode-comparison.md · Auto 模式（仅导出本节点，1 项）vs FullSpace 模式（展开整个知识库，38 项，前端默认）；
- 父文档带子页面整棵导出、空文档 / 超长标题 / 特殊字符文件名清洗与还原、重复导出自动编号。
需要自建服务器吗？我的数据会上传吗？
不需要、不会。LarkReader 是纯本地工具：无自建服务端、无遥测。内容通过你本机的 lark-cli（你自己的飞书账号 OAuth 授权）拉取，所有产物只写到你选择的本地目录。
飞书账号密码存在哪里？
LarkReader 不保存、也不接触飞书密码或 token。凭据由官方 lark-cli 在本机托管，LarkReader 只负责发起设备码登录和检测登录状态。
支持哪些内容类型？
Doc（docx 正文 → Markdown + 图片本地化）、Sheet → XLSX、Bitable → NDJSON（含 manifest 元数据）、file 节点附件（zip / pdf / docx 等原样字节）。不支持或失败的节点会在结果中分类如实上报，不会伪装成功。
重复导出会覆盖之前的文件吗？
不会。同名文件自动使用 (2)、(3) 等后缀；每次导出还会先写临时文件、成功后再原子提交，失败不会留下半截文件。
为什么锁死 lark-cli 1.0.93？
lark-cli 的写类命令（media-preview / workbook-export / record-list 等）有输出路径白名单等行为约束，固定已验证版本才能保证导出链路稳定可复现。版本不兼容时环境体检会明确报告并支持一键自动安装。
支持哪些平台？
Tauri 2 跨平台：Windows / macOS / Linux。推送 v* tag 后由 GitHub Actions 在三个平台出包并正式发布到 GitHub Releases（非 draft），应用内更新可直接拉取。
当前版本说明：v0.1.0 的 Releases 暂仅提供 Windows（x64）安装包，多平台产物将随发布流水线完善陆续补充。macOS / Linux 用户目前可参照「快速开始 → 开发者」从源码自行构建使用。
欢迎任何形式的贡献：提 issue、修 bug、补文档、加功能。动手前请先阅读 CONTRIBUTING.md（提交规范、前后端契约、npm run verify 门禁要求）；安全问题请勿公开 issue，走 SECURITY.md 说明的私密安全公告渠道。
- 本项目是一个飞书开放平台 API 的学习实践项目——如同学习一门编程语言后写一个应用来练手，项目内的接口本质上都是对飞书官方 API 的调用。通过官方 Open API 与官方 lark-cli、以使用者自己的账号授权，读取其有权限查看的内容；不破解、不绕过任何权限机制
- 导出内容的版权归原作者所有，仅限个人学习与备份，请勿用于传播或商业用途
- 使用者需自行遵守飞书用户协议、开放平台条款及所在组织的数据安全规定；因违反前述规定产生的后果由使用者自行承担
- 作者不对使用者的滥用行为负责；如权利人认为本工具存在侵权，请通过 Issues 联系，将积极配合处理
本项目以 GPL-3.0-only 授权。提交 PR 即表示同意贡献以同一许可发布。 版权年份：2026。
- LINUX DO — 「新的理想型社区」，本项目在 LINUX DO 社区进行开源推广，感谢佬友们的支持与反馈。
LPK3215 — 17538703215@163.com
- feat：本地阅读（Reader）页——浏览导出目录、渲染 Markdown 与图片，离线可用（
reader.rs+ 3 个 IPC 命令）； - feat：首次使用自动进入引导页（路由守卫），设置页新增「重新运行引导」入口；
- feat：lark-cli 安装支持自动 / 手动双方式，自动安装失败重试 3 次并写入运行日志；
- feat：登录环节设备码与授权链接均可一键复制（引导页 + 飞书终端页）；
- feat：运行日志页与后端日志查询命令（
list_log_files/read_log_file/open_log_dir）； - feat：环境管理页面与退出登录（
logout）；config init --new向导自动弹浏览器； - fix：登录改为单次阻塞式设备码等待（轮询会导致验证码失效）；
- fix：修复取消或超时后 lark-cli 子进程残留问题；
- chore：包管理器从 pnpm 迁移到 npm；剥离浏览器 mock 回退，仅保留真实 IPC；
- ci：Tauri 三平台发布流水线；docs：GPL-3.0 许可、贡献与安全说明。