# BlogPublish

**Repository Path**: alonecat06/blog-publish

## Basic Information

- **Project Name**: BlogPublish
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 飞书文档 → 博客园 发布工具 使用说明

将飞书云文档（Wiki / Docx）一键转换为 Markdown 并发布到博客园，支持图片自动迁移、重复发布检测、增量更新。

---

## 一、环境准备

### 1.1 系统要求

- Python 3.10+
- pip

### 1.2 安装依赖

```bash
pip install -r requirements.txt
```

依赖列表：

| 包名 | 用途 |
|------|------|
| requests | 飞书 API / 博客园 MetaWeblog 调用 |
| python-dotenv | 从 .env 文件加载配置 |
| Pillow | 图片压缩（超过 2MB 时自动压缩） |

---

## 二、配置

### 2.1 创建 .env 文件

复制 `.env.example` 为 `.env`，填入实际值：

```ini
FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CNBLOGS_USERNAME=your_cnblogs_username
CNBLOGS_TOKEN=your_cnblogs_metaweblog_token
```

### 2.2 获取飞书凭据

1. 登录 [飞书开放平台](https://open.feishu.cn/) → 创建应用
2. 获取 **App ID** 和 **App Secret**
3. 为应用添加以下权限：
   - `docx:document` — 读取文档内容
   - `wiki:wiki` — 读取知识库节点
   - `drive:drive` — 下载文档中的图片
   - `im:resource` — 下载 IM 图片（备用）
   - `board:board` — 导出画板为图片
4. 发布应用并确保目标文档对应用可见

### 2.3 获取博客园 Token

1. 登录博客园 → 设置 → MetaWeblog API
2. 启用 MetaWeblog 访问
3. 生成访问令牌（Token）

---

## 三、使用方法

### 3.1 发布文档

```bash
python feishu2cnblogs.py "https://xxx.feishu.cn/wiki/Fxn5wN5ygizHPVkA1fzcBw8EnbI"
```

支持的 URL 格式：

| 格式 | 示例 |
|------|------|
| 知识库 Wiki | `https://xxx.feishu.cn/wiki/xxxxxx` |
| 新版文档 Docx | `https://xxx.feishu.cn/docx/xxxxxx` |
| 旧版文档 Docs | `https://xxx.feishu.cn/docs/xxxxxx` |

### 3.2 指定分类

```bash
python feishu2cnblogs.py "https://xxx.feishu.cn/wiki/xxxxxx" -c "技术"
```

### 3.3 发布为草稿

```bash
python feishu2cnblogs.py "https://xxx.feishu.cn/wiki/xxxxxx" --draft
```

### 3.4 查看可用分类

```bash
python feishu2cnblogs.py --list-categories
```

### 3.5 调试模式

```bash
# 详细日志
python feishu2cnblogs.py "https://xxx.feishu.cn/wiki/xxxxxx" --verbose

# 静默模式（仅输出最终结果）
python feishu2cnblogs.py "https://xxx.feishu.cn/wiki/xxxxxx" --quiet
```

### 3.6 重复发布

对同一篇飞书文档重复执行发布命令时，工具会自动检测已有博文并**更新**而非重复创建。检测逻辑（按优先级）：

1. `history.json` 中的 URL 匹配
2. 博文内容中的 `<!-- feishu-doc: URL -->` 隐藏标识
3. 博文标题完全匹配

---

## 四、完整命令行参数

| 参数 | 缩写 | 说明 |
|------|------|------|
| `doc_url` | — | 飞书文档 URL（必填，`--list-categories` 除外） |
| `--category` | `-c` | 博客园分类名称 |
| `--draft` | — | 发布为草稿（不公开） |
| `--list-categories` | — | 列出博客园可用分类 |
| `--verbose` | — | 输出详细调试日志 |
| `--quiet` | — | 仅输出最终结果 |

---

## 五、工作流程

```
飞书文档 URL
    │
    ▼
解析 URL 类型（Wiki / Docx / Docs）
    │
    ▼
获取文档标题 + Block 列表
    │
    ▼
Block → Markdown 转换
    │
    ▼
图片迁移（飞书 → 博客园图床）
    │
    ▼
重复检测 → 新建 / 更新博文
    │
    ▼
记录到 history.json
```

---

## 六、支持的 Markdown 元素

| 飞书 Block 类型 | Markdown 输出 | 说明 |
|----------------|---------------|------|
| 标题 H1–H9 | `# ~ #########` | 完整支持 |
| 文本段落 | 普通文本 | 支持加粗/斜体/删除线/行内代码/链接 |
| 无序列表 | `* item` | 支持嵌套 |
| 有序列表 | `1. item` | 支持递增编号和嵌套 |
| 待办事项 | `- [x] / - [ ] item` | 支持嵌套 |
| 代码块 | ` ```lang ``` ` | 自动识别语言标签 |
| 引用块 | `> text` | 支持 quote_container 嵌套 |
| 分割线 | `***` | — |
| 图片 | `![alt](url)` | 自动迁移到博客园图床 |
| 画板 | `![diagram](url)` | 飞书画板自动导出为图片并迁移 |
| 表格 | Markdown 表格 | 支持普通表格和 Sheet |
| 背景色 | `<span style="background-color:...">` | HTML 内联样式 |

不支持的 Block 类型（callout、iframe、bitable 等）会以 HTML 注释形式保留占位：

```html
<!-- unsupported-block: callout -->
```

---

## 七、图片处理

- 自动检测 Markdown 中的飞书图片 token 和画板 ID
- 图片优先通过 Drive API 下载，失败时回退到 IM API
- 画板通过 Board API 导出为 PNG 图片
- 超过 2MB 的图片自动压缩（最长边 ≤ 1920px，JPEG 质量 85）
- 上传到博客园图床后替换 Markdown 中的图片链接
- 临时文件自动清理

---

## 八、项目文件说明

```
BlogPublish/
├── feishu2cnblogs.py      # 主入口脚本
├── feishu_client.py       # 飞书 API 客户端
├── block_to_markdown.py   # Block → Markdown 转换器
├── cnblogs_client.py      # 博客园 MetaWeblog 客户端
├── image_migrator.py      # 图片迁移与压缩
├── requirements.txt       # Python 依赖
├── .env.example           # 配置模板
├── .env                   # 实际配置（不纳入版本控制）
├── .gitignore             # Git 忽略规则
├── history.json           # 发布历史记录（自动生成，不纳入版本控制）
└── tests/
    ├── __init__.py
    └── test_block_to_markdown.py  # 单元测试
```

---

## 九、运行测试

```bash
python -m pytest tests/ -v
```

---

## 十、常见问题

### Q: 提示 "Missing configuration"

`.env` 文件不存在或缺少必填项。参考 [2.1 节](#21-创建-env-文件) 创建配置文件。

### Q: 飞书 API 返回权限错误

确认应用已添加所需权限且已发布，同时确认目标文档对应用可见（知识库需将应用添加为成员）。

### Q: 图片下载失败

飞书图片下载优先使用 Drive API（`/drive/v1/medias/{token}/download`），失败后自动回退到 IM API。如果两者均失败，图片链接会保留为原始 token 占位符。

### Q: 博客园编辑器显示为 TinyMCE 而非 Markdown

发布时已自动在 categories 中添加 `[Markdown]` 分类，博客园会使用 Markdown 编辑器。如果旧博文仍显示 TinyMCE，重新发布一次即可。

### Q: 如何强制重新创建博文（而非更新）

删除 `history.json` 中对应条目，然后重新执行发布命令。工具会通过标题或隐藏标识匹配已有博文。如需完全新建，需先在博客园手动删除旧博文。

### Q: 代码块语言识别不正确

工具会自动检测代码块前一行是否为语言标签（如 `python`、`hlsl`），如果是则将其作为代码块语言并移除该行。如果语言标签未被正确识别，可在飞书文档中将语言标签单独写在一行。