Flow Hugo Publisher

Hugo 文章托管发布技能。用于检测 hugo/git 环境、管理工作目录、引导或初始化 Git 仓库、启动本地预览、执行提交，并通过 GitHub Actions 自动部署到可访问的 GitHub Pages。支持全托管执行与人工介入确认，并记录/读取用户当前工作目录与对应 Git 状态。

Security Scan

The skill's instructions, file writes, and Git/GitHub actions are coherent with a Hugo publishing helper; it modifies your workspace and writes a local state file but does not request unrelated credentials or install remote code.

Purpose & Capability

Name/description match the runtime instructions: the skill checks for hugo/git, manages a Hugo workspace, initializes themes, creates commits and a GitHub Actions workflow, and pushes to origin. All requested actions are consistent with a Hugo publisher.

Instruction Scope

The SKILL.md instructs the agent to read/write files in the user workspace (hugo config, themes, .github/workflows/*, static/CNAME) and persist a JSON state file at ~/.openclaw/state/hugo-publisher-state.json. It will run shell commands (git, hugo, mkdir, printf, etc.) and may push to remote Git remotes. These actions are expected for the stated purpose, but the skill will modify repository files and push changes if the user allows — review before pushing.

Install Mechanism

Instruction-only skill with no install spec or downloaded code. No installation risk from external URLs; all operations are local shell commands and Git interactions.

Credentials

Registry metadata declares no required environment variables, which is acceptable because the skill relies on locally-configured git credentials (SSH keys or credential helpers) and network access to remote Git remotes. The SKILL.md does not attempt to read unrelated secrets. Users should be aware pushing requires existing Git authentication (not provided by the skill).

Persistence & Privilege

The skill persists state to ~/.openclaw/state/hugo-publisher-state.json and writes files inside the chosen workspace (including workflow files). always:false (no forced presence). Persisting its own state and creating repo files is coherent with its purpose, but these writes are permanent until the user removes them.

Assessment

This skill appears to do what it says: it will inspect and modify a Hugo workspace, create/modify files (themes, hugo config, .github/workflows/hugo-pages.yml, static/CNAME, a local deploy guide), run hugo and git commands, and may commit and push to your remote. Before installing or running it: 1) Prefer running it against a disposable or test repository first; 2) Ensure you understand which local directory you point it at — it will write files there and may run git init/add/commit/push; 3) Back up any important repo or verify branches/remotes to avoid accidental pushes to sensitive repos; 4) Confirm you have git/hugo installed and that your Git credentials (SSH key or credential helper) are configured — the skill assumes push/auth exist but does not request credentials; 5) Review the generated workflow file (.github/workflows/hugo-pages.yml) and deploy guide before pushing; 6) Use the skill’s manual intervention points (it documents them) to require confirmation before initializing git, committing, or enabling Actions. If you need the agent never to push autonomously, run it with manual-confirmation mode or avoid granting autonomous invocation to the agent in your environment.

Hugo 托管发布技能

面向 Hugo 文章发布场景，提供可重复、可恢复、可人工介入的托管流程。 本技能只关注发布链路，不参与文章具体内容创作。

触发场景

当用户表达以下意图时触发：

• 管理或发布 Hugo 文章
• 初始化 Hugo 工作目录
• 在本地预览 Hugo 站点
• 将文章变更提交到 Git
• 询问“当前在哪个目录、对应哪个 Git 仓库”

执行总则

1. 默认全托管执行：能自动完成的步骤优先自动完成。
2. 关键节点可人工介入：目录创建、初始化模板选择、git init、提交信息确认。
3. 每一步都更新状态文件；失败时保留现场并输出恢复建议。
4. 所有命令执行前，先输出“将要做什么 + 为什么”，执行后反馈结果。
5. 仅处理发布流程，不扩展到文章内容生成。
6. 每一步必须输出统一进度格式：[阶段/步骤] [状态] [下一步]。

状态文件约定

状态文件默认保存在：

~/.openclaw/state/hugo-publisher-state.json

字段定义见 references/state-schema.md，状态按“多工作目录项目”管理，最小闭环字段如下：

• activeWorkspace
• projects.<workspacePath>.gitRoot
• projects.<workspacePath>.currentBranch
• projects.<workspacePath>.lastPreviewCommand
• projects.<workspacePath>.lastCommitHash
• projects.<workspacePath>.updatedAt

托管工作流（分阶段）

每一步都必须回显进度，例如：

• [阶段A/步骤1] 进行中：检测 hugo/git 环境
• [阶段A/步骤1] 完成：环境通过；下一步进入工作目录确认
• [阶段B/步骤2] 等待用户：请确认是否创建目录 <workspacePath>

阶段 A：环境确认与安装（首次或环境变化时）

步骤 1：环境检测

检查命令：

command -v hugo >/dev/null 2>&1
command -v git >/dev/null 2>&1

判定规则：

• 两者都存在：进入阶段 B。
• 任一缺失：输出系统对应安装指引（见 references/workflow.md），暂停后等待用户确认继续。

阶段 B：初始化项目（首次进入某工作目录时）

步骤 2：工作目录管理（人工可介入）

输入优先级：

1. 用户本轮明确指定目录
2. 状态文件中的 workspacePath
3. 引导用户新建目录

若目录不存在，先提示并确认后创建：

mkdir -p "<workspacePath>"

步骤 3：Hugo 模板初始化（仅首次）

若目录下不存在 hugo.toml / hugo.yaml / hugo.json，视为未初始化 Hugo 站点，必须进入模板选择。

内置常用模板：

1. ananke（官方示例主题，通用博客）
2. PaperMod（技术博客常用，轻量）
3. Stack（内容型博客，侧边栏结构）
4. Docsy（文档站点，适合知识库）
5. blowfish（现代简洁，适合内容创作）

也允许用户输入自定义模板仓库地址（Git URL）。

初始化约定：

• 空站点：hugo new site "<workspacePath>"
• 内置/自定义主题：站点初始化后，拉取主题到 themes/<themeName>，并在 Hugo 配置中设置 theme。

模板来源、模板名称、初始化方式必须写入状态文件。

模板详情与选型建议见 references/template-catalog.md。

步骤 4：Git 仓库检测与引导创建（人工可介入）

检测是否为 Git 仓库：

git -C "<workspacePath>" rev-parse --is-inside-work-tree

若不是 Git 仓库，按自动引导策略执行：

git -C "<workspacePath>" init

然后提示并协助用户完成首次提交（可托管执行）。

步骤 5：测试文章预览（初始化验收）

在工作目录启动预览：

hugo server --buildDrafts --bind 127.0.0.1 --port 1313

要求：

• 输出预览地址（默认 http://127.0.0.1:1313）。
• 若端口占用，尝试 1314、1315 递增端口并记录实际命令到状态。
• 提示停止命令（通常 Ctrl+C）。

步骤 6：初始化提交（可选）

提交前检查：

git -C "<workspacePath>" status --short

若无改动，明确提示“无可提交内容”并仅更新状态。

若有改动，执行：

git -C "<workspacePath>" add .
git -C "<workspacePath>" commit -m "<commitMessage>"

提交信息需先向用户确认；用户未给出时使用建议模板：

docs(hugo): update post content and site config

步骤 7：GitHub Actions 首次发布验证（推荐）

当用户希望“发布并公网可访问”时，执行 GitHub Pages 部署引导：

1. 检查远程仓库（origin）是否存在并可 push
2. 创建/更新 .github/workflows/hugo-pages.yml
3. 在工作目录生成 hugo-github-deploy-guide.md
4. 引导用户在仓库 Settings 中开启 Pages（Source: GitHub Actions）
5. 推送分支触发 Actions 并等待部署完成
6. 输出站点 URL（通常为 https://<user>.github.io/<repo>/）
7. 发布前提醒用户可选配置自定义域名，并引导修改域名相关文件

完整模板与操作说明见 references/github-actions.md。

约束：hugo-github-deploy-guide.md 跟随 Hugo 工作目录存放，不写入 ~/.openclaw。

阶段 C：日常发布快路径（后续默认）

当 activeWorkspace 已完成初始化后，默认走快路径：

1. 检测未发布文章（content/ 下有未提交变更）
2. 若存在未发布文章，提醒用户先确认预览与编辑
3. 运行本地预览
4. 用户确认后执行提交与推送，触发 GitHub Actions 发布
5. 更新该工作目录对应项目状态

阶段 D：状态写回与读取确认

流程结束后写回状态，并向用户展示：

• 当前工作目录
• Git 根目录
• 当前分支
• 当前工作目录未发布文章数量（如有）
• 最近一次预览命令
• 最近一次提交哈希（如有）
• 最近一次部署 URL（如有）

最后固定输出：

• [完成] 发布流程已结束；下一步可直接走“未发布检测 -> 预览 -> 发布”

人工介入点

详细规范见 references/interaction-points.md。默认在下列节点进行可中断确认：

1. 新目录创建前
2. 首次 Hugo 初始化时模板选择确认（内置或自定义）
3. 非 Git 目录自动初始化前
4. Git commit 执行前（确认提交信息）
5. 首次写入 GitHub Actions 工作流前（确认是否启用自动部署）
6. 检测到未发布文章时，确认是否先预览再发布

失败恢复策略

见 references/validation-checklist.md，至少覆盖：

• 未安装 hugo/git
• 目录权限不足
• 非 Git 目录
• 端口占用
• 空提交
• commit 失败
• Actions 构建失败或 Pages 未启用

参考文档

• 工作流与命令模板
• 状态文件结构
• 人工介入规范
• 校验与恢复清单
• 模板目录与选型建议
• GitHub Actions 部署指南