# 托管流程校验与恢复清单（发布流程专用）

> 本清单只关注发布链路，不包含文章内容创作质量校验。

## 一、环境与依赖

```markdown
□ hugo 已安装：`command -v hugo`
□ git 已安装：`command -v git`
□ hugo 版本可用：`hugo version`
□ git 版本可用：`git --version`
```

恢复策略：

- 缺 hugo/git：输出安装命令并暂停。
- 版本命令失败：提示重装并重试检测。

---

## 二、目录与权限

```markdown
□ workspacePath 已确定且为绝对路径
□ 目录存在或已创建成功
□ 目录有可读写权限
```

恢复策略：

- 创建失败：提示权限问题，建议切换到用户有权限的目录。
- 路径非法：要求用户重新提供路径。

---

## 三、Git 仓库状态

```markdown
□ 可识别是否为 Git 仓库
□ 非仓库时已完成 git init 或用户明确拒绝
□ 当前分支可读取（如 `git branch --show-current`）
```

恢复策略：

- `git init` 失败：保留目录状态并输出错误原文。
- 分支名为空：提示“仓库已初始化但尚无提交”。

---

## 四、模板初始化

```markdown
□ 非 Hugo 站点时已进入模板选择
□ 支持内置模板与自定义模板 URL
□ 模板安装成功（themes/<themeName>）
□ Hugo 配置文件已设置 theme
□ 模板信息已写入状态（templateType/templateName/templateSource）
```

恢复策略：

- 模板下载失败：提示网络问题并允许改选其他模板。
- 自定义模板地址无效：提示重新输入合法 Git URL。
- 主题配置失败：回退到 `empty` 初始化并提示手动修复。

---

## 五、预览服务

```markdown
□ hugo server 命令可启动
□ 返回可访问地址（默认 127.0.0.1:1313）
□ 若端口占用，已尝试备用端口
□ 已提示如何停止预览服务
```

恢复策略：

- 端口占用：递增端口重试（1314、1315）。
- 启动失败：输出 Hugo 错误并建议先执行 `hugo` 构建定位问题。

---

## 六、未发布文章检测

```markdown
□ 已检测 `content/` 目录未提交变更
□ 已计算未发布文章数量
□ 检测到未发布文章时已提醒用户先预览
□ 用户确认后才继续发布
```

恢复策略：

- 检测命令异常：回退到全量 `git status --short` 并提示手动确认。
- 用户拒绝预览：保留二次确认提示，避免误发布。

---

## 七、提交流程

```markdown
□ 提交前已检测变更（git status --short）
□ 提交信息已确认
□ add/commit 命令执行成功
□ 已读取最新 commit hash
```

恢复策略：

- 无变更：跳过提交，仅更新状态。
- commit 失败：输出失败原因，保留已暂存状态供用户手动处理。

---

## 八、GitHub Actions 与 Pages 部署

```markdown
□ 已生成 `.github/workflows/hugo-pages.yml`
□ workflow 语法有效且包含 Hugo 构建步骤
□ 仓库 Pages Source 已设置为 GitHub Actions
□ 推送后 Actions 运行成功
□ 已获取并回显公开访问 URL
```

恢复策略：

- Actions 失败：输出失败步骤日志并给出修复建议（Hugo 版本、baseURL、主题子模块）。
- Pages 未启用：提示进入 Settings 手动开启后重试。
- 远程推送失败：提示检查 `origin`、权限和认证状态。

---

## 九、状态持久化（多工作目录）

```markdown
□ 状态文件可读取
□ 状态文件可写回
□ 存在 `activeWorkspace`
□ 存在 `projects[activeWorkspace]` 且关键字段完整
□ 已记录未发布文章状态（count/flag）
□ 结束时已回显当前目录与 Git/部署信息
```

恢复策略：

- 状态文件损坏：备份坏文件后重建最小结构。
- 状态写入失败：提示权限并输出当前内存态关键信息。

---

## 十、最小验收用例

1. 新用户首次使用（无状态、无目录、无仓库）可走通到预览。
2. 首次初始化时可选择内置模板或自定义模板。
3. 已有目录但非仓库，能自动引导初始化并继续。
4. 已有仓库直接走“检测未发布文章 -> 预览 -> 发布”快路径。
5. 有未发布文章时能提醒用户确认预览与发布。
6. 配置 Actions 后可自动部署到 GitHub Pages 并返回可访问 URL。
7. 多个工作目录切换时，状态可按项目维度正确保留与读取。