# Hugo 短代码功能 & Telegram Bot 适配

## ✅ 已实现功能

### 1️⃣ Hugo 短代码

#### 实况照片 (Live Photo)
```markdown
{{< livephoto image="photo.jpg" video="photo.mp4" >}}
```
- 悬停播放视频
- 点击切换播放/暂停
- 静音控制
- 自动检测图片比例

#### 语音气泡
```markdown
{{< voice src="voice.ogg" >}}
```
- 微信风格设计
- 点击播放语音
- 自动显示时长
- 未读标记（当天发布）

#### 音乐卡片
```markdown
{{< music-card src="song.mp3" name="歌曲名" artist="歌手" cover="cover.jpg" >}}
```
- 精美卡片设计
- 播放/暂停控制
- 进度条拖拽
- 时间显示

---

## 📱 Telegram Bot 使用指南

### 发送语音消息

**操作**：
1. 在写作模式下（`/new` 或 `/edit`）
2. 发送语音消息

**Bot 响应**：
```
🎙️ 正在处理语音...
✅ 语音已保存：1719234567-voice.ogg
📝 转文字：今天天气真好...
```

**生成内容**：
```markdown
{{< voice src="1719234567-voice.ogg" >}}

> 今天天气真好...
```

---

### 发送音频文件（MP3）

**操作**：
1. 在写作模式下
2. 发送 MP3 文件

**Bot 响应**：
```
🎵 正在处理音频文件...
✅ 音频已保存：1719234567-music.mp3

请输入歌曲信息（格式：歌名 - 歌手）：
```

**用户回复**：
```
晴天 - 周杰伦
```

**Bot 响应**：
```
🎵 歌曲：晴天
🎤 歌手：周杰伦

是否添加封面图？
[📷 添加封面图] [⏭️ 跳过]
```

**选项 A - 添加封面图**：
1. 点击 "添加封面图"
2. 发送图片
3. Bot：✅ 封面图已保存：cover.jpg
4. 生成带封面的音乐卡片

**选项 B - 跳过**：
1. 点击 "跳过"
2. 直接生成不带封面的音乐卡片

**生成内容**：
```markdown
{{< music-card src="1719234567-music.mp3" name="晴天" artist="周杰伦" cover="cover.jpg" >}}
```

---

### 发送图片

**操作**：
1. 在写作模式下
2. 发送图片

**Bot 响应**：
```
📷 图片已保存：1719234567-photo.jpg

💡 提示：如果您发送的是 iOS 实况照片（Live Photo），
动态效果无法自动提取。如需保留动态效果，请：

1. 将实况照片转为视频/GIF 后重新发送
2. 或者单独发送视频部分

继续发送其他内容...
```

**生成内容**：
```markdown
![image](1719234567-photo.jpg)
```

---

## 🎯 功能特性

### PJAX 支持
- 所有短代码支持 PJAX 无刷新页面切换
- 自动重新初始化交互逻辑
- 保持播放状态

### 暗黑模式
- 自动适配暗黑主题
- 深色背景优化
- 高对比度设计

### 响应式设计
- 移动端友好
- 触摸操作支持
- 自适应布局

---

## 🛠️ 技术实现

### 文件结构

**Hugo 主题 (ying)**：
```
themes/ying/
├── layouts/shortcodes/
│   ├── livephoto.html
│   ├── voice.html
│   └── music-card.html
├── assets/css/
│   └── shortcodes.css
└── assets/js/
    └── shortcodes.js
```

**Telegram Bot (write-server)**：
```
write-server/src/lib/bot/
├── poll.ts
│   ├── handleVoiceEnhanced()  # 语音增强
│   ├── handleAudioEnhanced()  # 音频处理
│   ├── handlePhotoEnhanced()  # 图片增强
│   ├── handleAudioInfoEnhanced()  # 音频信息
│   └── handleAudioCoverCallback() # 封面图回调
└── handlers.ts
```

### API 集成
- Artalk 评论系统
- Telegram Bot API
- Hugo 静态生成

---

## 📝 部署检查清单

- [ ] 提交 ying 主题修改
- [ ] 提交 write-server 修改
- [ ] 推送到远程仓库
- [ ] 重新构建 Hugo 站点
- [ ] 部署 write-server
- [ ] 测试语音消息
- [ ] 测试音频文件
- [ ] 测试图片上传
- [ ] 验证短代码渲染
- [ ] 测试 PJAX 页面切换
- [ ] 测试暗黑模式

---

## 🐛 故障排除

### 语音不播放
- 检查音频文件路径
- 确认文件格式支持（OGG, MP3）
- 查看浏览器控制台错误

### 音乐卡片无响应
- 检查 JS 是否正确加载
- 确认 PJAX 初始化
- 刷新页面重试

### 封面图不显示
- 检查图片路径
- 确认文件已保存
- 查看 Hugo 构建日志

---

## 📚 相关链接

- [Hugo 短代码文档](https://gohugo.io/content-management/shortcodes/)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [Amigo 主题](https://github.com/zqlit/Hugo-Theme-Amigo)

---

## 📊 版本历史

**v1.0.0** (2026-06-24)
- ✅ 移植 Amigo 主题短代码
- ✅ Telegram Bot 语音增强
- ✅ Telegram Bot 音频文件支持
- ✅ 封面图上传功能
- ✅ 实况照片引导提示
- ✅ PJAX 支持
- ✅ 暗黑模式适配