# 发布文档规范

## 文档定位

发布文档面向**最终用户**，不是技术开发日志。内容应该简洁、清晰、有价值。

## 内容风格

### ✅ 推荐写法

- **用户视角**：描述功能带来的价值，而非技术实现
- **简洁明了**：每条更新 1-2 句话，避免冗长
- **分类清晰**：按功能模块或改进类型分组

**示例**：

```markdown
## 核心功能

- 新增 Playwright 浏览器自动下载，首次启动自动从 S3 获取。
- 实时显示下载进度（百分比、速度、剩余时间）。
```

### ❌ 避免写法

- 技术细节（文件路径、代码实现、架构设计）
- 开发过程描述（"重构了"、"优化了算法"）
- 过长的段落（超过 2 行）

## 文档结构

### 标准格式

```markdown
# {版本号}

## {分类 1}

- {更新点 1}
- {更新点 2}

## {分类 2}

- {更新点 1}
- {更新点 2}
```

### 常见分类

- `核心功能` - 新功能、重大特性
- `改进` / `体验优化` - 现有功能优化
- `问题修复` - Bug 修复
- `界面与交互` - UI/UX 改进

## 篇幅要求

- **小版本**（x.x.1）：5-10 行
- **中版本**（x.x.0）：10-20 行
- **大版本**（x.0.0）：20-40 行

## 示例参考

### 简洁版（1.4.2）

```markdown
# 1.4.2

## 架构优化

- 重构主进程启动流程和 IPC 编排层，按领域拆分 preload API。
- 解耦更新服务职责，对话框改为懒加载以优化性能。

## 质量改进

- 修复类型检查问题，加固启动流程和认证健壮性。
- 新增核心模块测试覆盖，完善开发者文档。
```

### 详细版（1.4.0）

```markdown
# 1.4.0

## 亮点

- 新增 Windows 便携版自动更新能力，支持 `stable` / `preview` 双通道发布。
- 更新策略与登录用户角色联动。

## 自动更新

- 新增便携版更新服务，支持登录后自动检查更新。
- 更新器采用原生 `portable-updater.exe`，不再依赖 PowerShell 脚本。
```

## 发布流程

1. 创建版本文件：`docs/releases/{version}.md`
2. 参考现有文档风格编写
3. 提交 git：`git add docs/releases/{version}.md`
4. 提交信息：`docs: add release notes for version {version}`

## 维护说明

- 发布文档一旦创建，**不再修改**（除非有重大错误）
- 技术细节放入 `docs/` 下的专题文档
- Changelog 由发布脚本自动生成，不手动维护