- name: Setup Hugo
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: '0.147.9'
    extended: true

# 示例：使用官方镜像启动本地预览服务
docker run --rm -it \
  -v $(pwd):/src \
  -p 1313:1313 \
  ghcr.io/gohugoio/hugo:latest server --bind 0.0.0.0

skills/
└── hugo-blog-manager/
    ├── SKILL.md
    └── scripts/
        ├── _common.ps1          # 公共函数：DryRun 预演、hugo 定位、UTF-8 写文件
        ├── check_env.ps1        # 只读环境体检
        ├── install_hugo.ps1     # 安装 hugo（本地 winget / Docker）
        ├── init_site.ps1        # 新建站点 + git init
        ├── install_theme.ps1    # 装主题并写入 theme:
        ├── preview.ps1          # hugo server 本地预览
        ├── push_github.ps1      # 提交并推送
        └── setup_actions.ps1    # 生成 GitHub Actions 部署 workflow

---
name: hugo-blog-manager
description: 管理 Hugo 博客：从零创建站点、选装主题、推送 GitHub 并配置 GitHub Actions 自动部署到 GitHub Pages；以及安全地修改现有站点的内容、Front Matter、布局、样式和配置（先给 diff 再逐步确认，hugo server 本地预览，构建或发布失败排错）。当用户说“部署 Hugo 博客”“新建 Hugo 站点”“修改 Hugo 页面”“改页脚”“加关于页”“博客发不出去/Pages 404”或提到 Hugo、GitHub Pages、hugo.yaml 时使用。安装 Hugo 本体必须先让用户在“本地安装 / Docker 安装”之间选择；主题必须在安装那一刻现场询问用户。
metadata:
  nanobot:
    emoji: 📝
    requires:
      bins: ["git"]
---

# Hugo 博客管理器

两个工作流：**流程 A 部署新博客**、**流程 B 安全修改现有站点**。

脚本目录（下文记作 `$S`，调用时替换成这个技能的真实路径）：

```
$S = <skills>\hugo-blog-manager\scripts
```

运行时的当前目录不是技能目录，**调用脚本必须用绝对路径**。

## 两条硬性规则

1. **Hugo 本体安装必须先问用户**。只能在用户明确选择「本地安装」（winget `Hugo.Hugo.Extended`）或「Docker 安装」（拉 hugo 镜像，用 `docker run` 跑）之后，才通过 `install_hugo.ps1` 执行。不要自动安装，不要替用户选。
2. **主题必须现场问用户**。本技能不预设任何主题。走到装主题那一步时，先给 3~4 个候选（各自特点 + 仓库地址）让用户挑，选定后才跑 `install_theme.ps1`。

## 确认式执行

每个关键节点三步走：先跑 `-DryRun` → 把命令和影响讲给用户 → 用户明确同意后去掉 `-DryRun` 实跑。

## 全局前置检查

```powershell
powershell -NoProfile -File "$S\check_env.ps1"
```

只读体检（hugo / git / docker / winget），退出码 `0`=就绪、`1`=hugo 缺失、`2`=git 缺失、`3`=两者都缺。hugo 缺失时**不要自己装**，转去问用户选哪种方式：

```powershell
powershell -NoProfile -File "$S\install_hugo.ps1" -Method Local  -DryRun   # 本地安装
powershell -NoProfile -File "$S\install_hugo.ps1" -Method Docker -DryRun   # Docker 安装
```

装完重跑 `check_env.ps1` 确认；本地安装后若 `hugo` 仍不可见，提醒用户新开终端刷新 PATH。

## 流程 A：部署新博客

按顺序走，每步先 DryRun 再等确认。

1. **环境检查** —— 见上。
2. **确定站点位置与标题** —— 问用户博客放哪个目录、叫什么名字（`baseURL` 后续可改）。
3. **创建站点**：`init_site.ps1 -SitePath "<目录>" -Title "<标题>"` → `hugo new site --format yaml` + `git init -b main` + 写 `hugo.yaml` 与 `.gitignore`。目标目录必须为空，脚本拒绝覆盖已有内容。
4. **选主题（必须先问用户）**：`install_theme.ps1 -SitePath "<目录>" -ThemeName <名> -ThemeRepo <仓库地址>`。默认走 `git submodule`（主题可后续升级）；GitHub 不可达时脚本会报错并提示改用 `-Mode Zip -ZipUrl <镜像 zip 地址>`。
5. **本地预览，交给用户确认**：`preview.ps1 -SitePath "<目录>"`（`hugo server`，默认 http://127.0.0.1:1313/）。这是前台长进程，用后台会话跑；**界面效果必须由用户在浏览器确认**，不要用 HTTP 探测 localhost 代替。
6. **建 GitHub 仓库**（让用户在网页端建，**不要勾 README / .gitignore**），然后推送：
   `push_github.ps1 -SitePath "<目录>" -RepoUrl https://github.com/<user>/<repo>.git -Message "Initial commit: Hugo blog"`
7. **配置自动部署**：`setup_actions.ps1 -SitePath "<目录>"` 写 `.github/workflows/hugo.yaml` 并推送。Hugo 版本自动取自本地 hugo 或 hugo 容器，也可 `-HugoVersion x.y.z` 指定。
8. **收尾**：提醒用户去仓库 `Settings → Pages → Source` 选 **GitHub Actions**（一次性手动步骤），之后每次 push 自动发布。

## 流程 B：安全修改现有站点

1. **先读再动**。定位改动点：`hugo.yaml`（站点配置）、`content/`（文章 / Front Matter）、`layouts/`（模板覆盖）、`assets/` 与 `static/`（样式、静态资源）、`themes/<主题>/`（主题源码）。
2. **主题是外部代码（submodule），默认不改它内部文件**。优先在站点根目录放同名文件覆盖（Hugo 的 lookup order），例如 `layouts/partials/footer.html`。确实必须改主题内部时，先说明代价（升级会被覆盖，或需要 fork）再决定。
3. **每处改动都是三步**：读原文 → 把 diff（改什么、为什么、影响哪些页面）给用户看 → 等确认 → 再改。一次只改一处，别攒一堆一起改。
4. **改完必看**：`preview.ps1` 让用户在浏览器确认效果；改模板时可用 `-Drafts` 连草稿一起看。
5. **用户认可后再提交**：`push_github.ps1 -SitePath "<目录>" -RepoUrl <origin> -Message "<改了什么>"`。
6. **不可逆操作先备份**：删内容、换主题、改 `baseURL`、重写 git 历史之前，先复制目录或开新分支。

### 常见排错

- **Pages 404 / 页面不更新**：仓库 `Settings → Pages → Source` 必须是 `GitHub Actions`；`baseURL` 与实际域名不一致时由 workflow 的 `--baseURL` 兜底。
- **样式没生效**：核对主题的 `assets` / `static` 目录结构，以及 `hugo.yaml` 里的 `theme` 值与 `themes/` 下的目录名是否一致。
- **构建失败**：看 Actions 日志；本地 hugo 版本与主题要求不匹配时，用 `setup_actions.ps1 -HugoVersion` 重新生成 workflow。
- **CI 里主题目录是空的**：workflow 的 checkout 已带 `submodules: recursive`；若仍为空，确认 `.gitmodules` 已提交进仓库。
- **用户站点仓库（`<user>.github.io`）**：`baseURL` 必须是根域名（如 `https://mythstraw.github.io/`）；私有仓库开 Pages 需付费，必须 public。

## Hugo 陷阱速查

- `T` / `i18n` 返回值会被 HTML 转义 → 翻译串含 `<a>` 时必须 `| safeHTML`。
- 模板内链接用 `.RelPermalink`；`relURL` 在带语言前缀时会重复加前缀。
- 首页 `.Title` 为空 → 判断首页必须用 `.IsHome`。
- front matter 不写 `slug` 时 Hugo 用**标题**做 URL（中文标题 → 百分号编码）→ 每篇显式写 `slug`。
- `buildFuture=false`（默认）：`date` 写成未来时间会被整篇跳过。
- 用 Docker 跑 hugo 必须把站点子目录挂成工作目录（挂整盘会报 "Unable to locate config file"）。

## 脚本清单

| 脚本 | 作用 | 关键参数 |
| --- | --- | --- |
| `check_env.ps1` | 只读环境体检 | `-Json` |
| `install_hugo.ps1` | 安装 hugo（**须用户先选方式**） | `-Method Local\|Docker`、`-StartEngine` |
| `init_site.ps1` | 新建站点 + git init + 配置 + .gitignore | `-SitePath`、`-Title`、`-BaseUrl`、`-LanguageCode` |
| `install_theme.ps1` | 装主题并写入 `theme:`（**主题须现场问用户**） | `-ThemeName`、`-ThemeRepo`、`-Mode Submodule\|Zip` |
| `preview.ps1` | `hugo server` 本地预览 | `-Port`、`-Drafts`、`-BindAddress` |
| `push_github.ps1` | 提交并推送到 GitHub | `-RepoUrl`、`-Branch`、`-Message`、`-Rebase` |
| `setup_actions.ps1` | 生成 GitHub Actions 部署 workflow | `-HugoVersion`、`-Branch`、`-NoPush` |

# 有原生 hugo 就原生跑；没有原生 hugo 但 Docker 引擎在跑，就用容器跑
function Invoke-Hugo {
    param(
        [Parameter(Mandatory = $true)][string]$SitePath,
        [Parameter(Mandatory = $true)][string[]]$HugoArgs,
        [string]$MountPath = '',
        [string]$Image = 'hugomods/hugo:exts',
        [string[]]$ExtraDockerArgs = @(),
        [switch]$DryRun
    )
    $status = Get-HugoStatus
    if ($status.Mode -eq 'native') {
        $line = ('cd "{0}"; hugo {1}' -f $SitePath, ($HugoArgs -join ' '))
        if ($DryRun) { Write-Output "DRY-RUN: $line"; return }
        # ... 实跑，退出码非 0 就抛错
    }
    if ($status.Mode -eq 'docker') {
        $mount = $MountPath; if (-not $mount) { $mount = $SitePath }
        $src = ConvertTo-PosixPath $mount      # E:\myblog -> /e/myblog
        $dkArgs = @('run', '--rm') + $ExtraDockerArgs + @('-v', "${src}:/src", '-w', '/src', $Image, 'hugo') + $HugoArgs
        if ($DryRun) { Write-Output ('DRY-RUN: docker ' + ($dkArgs -join ' ')); return }
        # ... 实跑，退出码非 0 就抛错
    }
    throw "hugo is not available: neither a native 'hugo' executable nor a running Docker engine was found. Run install_hugo.ps1 first (ask the user to choose Local or Docker)."
}

$hugo   = Get-HugoStatus      # native / docker / none
$git    = Get-GitExe
$docker = Test-DockerEngine   # client / engine / version

$missing = @()
if ($hugo.Mode -eq 'none') { $missing += 'hugo' }
if (-not $git)             { $missing += 'git' }

# exit code: 0 ready, 1 hugo missing, 2 git missing, 3 both missing
$exitCode = 0
if ($missing -contains 'hugo') { $exitCode += 1 }
if ($missing -contains 'git')  { $exitCode += 2 }

if ($missing -contains 'hugo') {
    Write-Output 'NEXT: hugo is missing. Do NOT install silently - ask the user to pick one:'
    Write-Output '  A) local install  : powershell -NoProfile -File install_hugo.ps1 -Method Local    (winget Hugo.Hugo.Extended)'
    Write-Output '  B) docker install : powershell -NoProfile -File install_hugo.ps1 -Method Docker   (needs Docker Desktop running)'
}

if ($Method -eq 'Local') {
    $wgArgs = @('install', '--id', $WingetId, '-e', '--accept-source-agreements', '--accept-package-agreements')
    if ($DryRun) { Write-Output ('DRY-RUN: {0} {1}' -f $winget, ($wgArgs -join ' ')); exit 0 }
    & $winget @wgArgs
    $after = Get-HugoStatus
    if ($after.Mode -eq 'native') { Write-Output ("OK: hugo {0} -> {1}" -f $after.Version, $after.Exe); exit 0 }
    # ... 仍不可见时给出提示（下载被墙、需刷新 PATH、或改用 Docker）
}

# Docker 方式：引擎没起时可加 -StartEngine，最多等 240 秒
& $docker pull $Image
& $docker run --rm $Image hugo version

if (Test-Path -LiteralPath $sitePath) {
    $entries = @(Get-ChildItem -LiteralPath $sitePath -Force | Where-Object { $_.Name -ne '.' })
    if ($entries.Count -gt 0) {
        Write-Fail "Target directory is not empty: $sitePath. Pick another path, or clean it up first (refusing to touch existing content)." 4
    }
}

Invoke-Hugo -SitePath $parent -MountPath $parent -Image $Image -DryRun:$DryRun `
    -HugoArgs @('new', 'site', $leaf, '--format', 'yaml')

# 新站点没有需要保留的内容，直接写一份干净的 hugo.yaml（theme: 留到装主题那步再写）
$config = @"
baseURL: "$BaseUrl"
languageCode: "$LanguageCode"
title: "$Title"
"@
New-Utf8File -Path $configPath -Content $config      # UTF-8 无 BOM，避免中文标题乱码

# 先探活：不通就明确告诉用户「加速器没开」或「改用 -Mode Zip」
$probe = & $git ls-remote $ThemeRepo HEAD 2>&1
if ($LASTEXITCODE -ne 0) {
    Write-Fail "Cannot reach $ThemeRepo" 3
}

& $git -C $sitePath submodule add $ThemeRepo "themes/$ThemeName"
& $git -C $sitePath submodule update --init --recursive

# -Mode Zip 分支：下载 + 解压到 themes/<名>
Invoke-WebRequest -Uri $ZipUrl -OutFile $tmpZip -UseBasicParsing -TimeoutSec 300
Expand-Archive -LiteralPath $tmpZip -DestinationPath $tmpDir -Force

# 把 theme: 写进配置（已有就替换，没有就追加）
if ($content -match '(?m)^\s*theme\s*[:=]') {
    $newContent = [regex]::Replace($content, '(?m)^\s*theme\s*[:=].*$', $line)
}
New-Utf8File -Path $configPath -Content $newContent

$status = Get-HugoStatus
if ($status.Mode -eq 'none') {
    Write-Fail "hugo is not available. Run check_env.ps1, then ask the user to choose Local or Docker install." 1
}

# 容器模式：容器内监听 0.0.0.0，端口发布在宿主机回环地址上
$innerBind = $BindAddress
$extra = @()
if ($status.Mode -eq 'docker') {
    $innerBind = '0.0.0.0'
    $extra = @('-p', ("{0}:{1}:{1}" -f $BindAddress, $Port))
}

$hugoArgs = @('server', '--port', "$Port", '--bind', $innerBind)
if ($Drafts) { $hugoArgs += '-D' }

# 1) git 身份没配就中止，绝不以未知作者提交
if (-not $email -or -not $name) {
    Write-Fail 'git user.name / user.email are not configured. Ask the user for them and re-run with -GitUserName / -GitUserEmail.' 4
}

# 2) 工作区干净就跳过 commit（不是报错）
$status = (& $git -C $sitePath status --porcelain 2>$null)
if ($status) {
    Invoke-Git -GitArgs @('-C', $sitePath, 'add', '-A')
    Invoke-Git -GitArgs @('-C', $sitePath, 'commit', '-m', $Message)
}

# 3) 远端已有提交时中止，除非显式 -Rebase
$remoteHeads = (& $git ls-remote --heads origin $Branch 2>$null)
if ($remoteHeads -and $LASTEXITCODE -eq 0) {
    if (-not $Rebase) {
        Write-Fail "Remote is not empty. Re-run with -Rebase to pull remote commits first, or push to another repo/branch." 4
    }
    Invoke-Git -GitArgs @('-C', $sitePath, 'pull', '--rebase', 'origin', $Branch)
}

Invoke-Git -GitArgs @('-C', $sitePath, 'push', '-u', 'origin', $Branch) -AllowFail

if (-not $HugoVersion) {
    $status = Get-HugoStatus
    if ($status.Mode -eq 'native') {
        $HugoVersion = Get-HugoVersionFromString -Text $status.Version
    }
    elseif ($status.Mode -eq 'docker') {
        $raw = @(& $status.Exe run --rm $Image hugo version 2>$null) -join ' '
        $HugoVersion = Get-HugoVersionFromString -Text $raw
    }
}

# 模板里占位，再替换成真实版本号与分支，UTF-8 无 BOM 写出
$workflow = $template.Replace('__HUGO_VERSION__', $HugoVersion).Replace('__BRANCH__', $Branch)
New-Utf8File -Path $workflowPath -Content $workflow

# 交给 push_github.ps1 提交推送（复用同一套身份/远端/分支保护）
& (Join-Path $PSScriptRoot 'push_github.ps1') -SitePath $sitePath -RepoUrl $remote -Message $Message