# 图片上传功能规格说明

## Why
当前 obsidian-halo 插件无法将本地图片上传到 Halo 媒体库，导致发布的文章中的图片无法正常显示。这是一个核心功能缺失，直接影响使用体验。

## What Changes
- 新增图片检测模块：解析 Markdown 中的本地图片引用
- 新增图片上传服务：调用 Halo 媒体 API 上传图片
- 新增图片路径替换：自动将本地路径替换为 Halo 远程 URL
- 新增设置选项：允许用户开关自动上传功能

## Impact
- 影响规格：
  - 发布功能：发布时自动处理图片
  - 设置功能：新增图片上传相关配置
- 影响代码：
  - 新增 `src/utils/image.ts`：图片处理工具函数
  - 新增 `src/service/image-uploader.ts`：图片上传服务
  - 修改 `src/service/index.ts`：集成图片上传到发布流程
  - 修改 `src/settings.ts`：添加图片上传设置项
  - 修改 `src/i18n/locales/*.json`：添加国际化文案

## ADDED Requirements

### Requirement: 图片自动上传
系统 SHALL 在发布文档时自动检测并上传本地图片到 Halo 媒体库。

#### Scenario: 检测到本地图片
- **WHEN** 用户执行发布命令且文档中包含本地图片（如 `assets/image.png`）
- **THEN** 系统自动上传图片到 Halo 并将文档中的路径替换为远程 URL

#### Scenario: 图片已上传过
- **WHEN** 系统检测到相同图片（基于文件路径和修改时间）
- **THEN** 直接使用已上传的 URL，不重复上传

#### Scenario: 上传失败
- **WHEN** 图片上传过程中发生错误
- **THEN** 系统记录错误并继续处理其他图片，已失败的图片保持原路径

### Requirement: 图片路径识别
系统 SHALL 支持识别以下格式的图片引用：
- `![alt](assets/image.png)` - 普通 Markdown 图片语法
- `![alt](./assets/image.png)` - 相对路径
- `![alt](/assets/image.png)` - 绝对路径（Vault 根目录）
- `![](data:image/png;base64,...)` - Base64 内联图片（可选支持）

### Requirement: 上传配置选项
系统 SHALL 提供以下配置选项：
- 开关：是否启用自动图片上传
- 媒体库路径：上传到 Halo 的哪个媒体目录
- 保留原图：是否保留本地路径作为备选

## MODIFIED Requirements

### Requirement: 发布流程
原发布流程：
1. 读取文档内容
2. 解析 frontmatter
3. 提交到 Halo API

修改后的发布流程：
1. 读取文档内容
2. 解析 frontmatter
3. **检测并上传本地图片**
4. **替换图片路径为远程 URL**
5. 提交到 Halo API

## REMOVED Requirements

无

---

## 技术实现细节

### Halo 媒体上传 API

```
POST /apis/api.console.halo.run/v1alpha1/attachments/upload
Content-Type: multipart/form-data

请求体：
- file: 二进制文件数据
- groupName: 媒体分组名称（可选）

响应：
{
  "name": "uuid-filename.png",
  "url": "/upload/2024/01/abc.png",
  "type": "IMAGE",
  "size": 12345
}
```

### 图片检测正则
```typescript
const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
```

### 配置项
```typescript
interface ImageUploadSettings {
  enabled: boolean;           // 是否启用
  uploadPath: string;         // 上传路径（空表示根目录）
  preserveOriginal: boolean;  // 保留原路径
}
```