飞书知识库 1:1 离线 Tailwind HTML 克隆引擎 (feishutohtml)

🚀 现代化、像素级还原的飞书（Feishu / Lark）云文档与知识库离线化工具。将飞书知识库高保真转换为纯净、优雅、免依赖的 Tailwind CSS + 语义化 HTML 静态站点。

---

✨ 核心特性

• 🎨 1:1 像素级现代排版：彻底摒弃飞书原始 Slate 框架的深层无序 DOM 嵌套，将文档结构转换为现代 Tailwind CSS 语义化布局（860px 阅读版心、平滑行距与优雅字阶）。
• 🔒 100% 纯净离线可用：所有静态依赖（Tailwind 运行库、Prism.js 语法高亮、样式表及文档高清配图）全部本地化存储，拔掉网线依然丝滑可用。
• ⚡ 原生双栏防卡死布局：严格规范 Flex 弹性视口架构，左侧导航树与右侧正文各自独立滚动，彻底杜绝外层 overflow: hidden 导致的页面滚动锁死 Bug。
• 🔍 左侧导航实时检索：内置极速轻量级客户端搜索，毫秒级响应标题过滤定位。
• 💻 全特性代码块与工具卡：支持数十种编程语言语法高亮、自动识别多行代码、Mac 风格控制栏及一键复制代码。
• 📦 附件与资源包通用离线化：对知识库中的文件/ZIP 附件提供自动化下载、归档组件动态扫描展示及在线代码速览。
• ⏱️ 断点续传与内存防护：批处理单篇原子落盘，实时记录 batch_progress.json，遭遇中断直接继续；自动执行内存主动清理，长篇连续克隆不崩溃。
• 🩺 自动化质量核验器 (Verifier)：生成完毕后一键扫描全站，自动检测图片 404、代码块语法高亮及坏链异常。

---

🛠️ 准备工作

1. 环境要求

• Python: 3.8 或更高版本
• Google Chrome: 现代版本浏览器

2. 安装依赖

pip install -r requirements.txt

3. 配置凭证

复制环境变量模板：

cp .env.example .env

在 .env 中填入以下信息（或直接使用向导模式自动填写）：

• FEISHU_DOMAIN：你的飞书域名（如 your-org.feishu.cn）
• FEISHU_COOKIE：飞书网页登录凭证（浏览器 F12 控制台 Network 请求头中复制）
• ROOT_WIKI_TOKEN：目标知识库根节点 Token 或完整 URL

---

🚀 快速上手

模式一：交互式配置向导（新手推荐）

直接运行主程序，跟随终端指引输入 URL/Token 与 Cookie：

python3 main.py

向导将自动反查知识库空间 ID、拉取完整目录拓扑树并提供克隆范围选择。

模式二：命令行批处理模式 (CLI)

# 全量离线克隆所有文档
python3 main.py --start 1 --end 143

# 克隆指定篇目 (例如第 1 篇至第 10 篇)
python3 main.py --start 1 --end 10

# 强制重新抓取并覆盖已有页面 (忽略断点续传)
python3 main.py --start 1 --end 5 --force

# 对当前已生成的离线站点进行质量与坏链核验
python3 main.py --verify

---

📂 站点输出规范

离线站点输出路径可在 .env 中通过 OUTPUT_DIR 自定义（默认输出至当前项目父目录）：

OUTPUT_DIR/
├── index.html                  # 站点入口，自动跳转至第 1 篇
├── css/
│   ├── tailwind.min.js         # 本地 Tailwind CSS 运行库
│   ├── prism.min.js            # Prism.js 核心语法高亮引擎
│   └── prism-tomorrow.min.css  # 现代深色代码主题样式
├── images/                     # 集中存放所有文档高清配图 (img_<hash>.png/jpg)
├── files/                      # 知识库附件及压缩归档文件
└── pages/                      # 离线文档页面 (001.html, 002.html, ...)
    ├── 001.html
    ├── 002.html
    └── ...

---

📄 开源许可

本项目遵循 MIT License 开源。仅供个人离线学习、归档与备份使用，请遵守飞书平台使用条款与相关版权规定。