用 Claude Agent Skills 实现博客一键发布：从繁琐流程到自然语言交互

./check_sensitive.sh

python publish.py \
  -f "ready/article.md" \
  -t "文章标题" \
  -c tech \
  --tags "标签1,标签2" \
  -d "文章描述"

python sync.py

# 4. 预览
cd blog && hugo server -D

# 5. 部署
cd blog && hugo && git add . && git commit -m "..." && git push

我：帮我发布这篇文章

Claude：
✅ 已检查敏感信息
✅ 已发布文章到 Hugo
✅ 已同步到 Obsidian
✅ 已构建并部署
🎉 发布完成！文章已上线。

用户请求（"帮我发布文章"）
    ↓
Claude 自然语言理解
    ↓
匹配相应 Skill
    ↓
加载 Skill Prompt
    ↓
执行具体步骤
    ├─ 读取文件
    ├─ 运行命令
    ├─ 处理数据
    └─ 返回结果
    ↓
友好的用户反馈

---
Date: 2024-11-13
tags:
  - 标签1
  - 标签2
project: 项目名
---

+++
title = "文章标题"
date = "2024-11-13"
lastmod = "2024-11-13"
author = ["geekhuashan"]
draft = false
categories = ["tech"]
tags = ["标签1", "标签2"]
description = "文章描述"
+++

![obsidian-hugo-complete-publishing-system-1.png](/tech/obsidian-hugo-complete-publishing-system-1.png)
![Pasted image 20230320223703.png](/Pasted image 20230320223703.png)

![Mac Mini 实物图](/tech/mac-mini.png)
![配置截图](/tech/pasted-image-20230320223703.png)

Main/
├── 07 blog idea/           # 博客草稿（混合存放）
│   ├── draft/             # 写作中的草稿
│   ├── ready/             # 待发布队列
│   └── published/         # 已发布备份
└── Attachment/             # 所有附件统一存放
    ├── Mac mini.png
    └── ...

blog/
├── content/posts/          # 按分类组织文章
│   ├── tech/
│   ├── read/
│   ├── life/
│   └── project/
└── static/                 # 按分类组织图片
    ├── tech/
    ├── read/
    └── life/

def generate_toml_front_matter(self, metadata: Dict) -> str:
    """生成 TOML Front Matter"""
    toml_lines = ["+++"]

    # 字符串字段 - 需要引号包裹
    toml_lines.append(f'title = "**metadata["title"]**"')
    toml_lines.append(f'date = "**metadata["date"]**"')
    toml_lines.append(f'lastmod = "**metadata["lastmod"]**"')

    # 数组字段 - 需要方括号和引号
    toml_lines.append(f'author = ["**metadata["author"]**"]')
    toml_lines.append(f'categories = ["**metadata["category"]**"]')

    # 标签数组 - 动态生成
    if metadata['tags']:
        tags_str = ", ".join([f'"**tag**"' for tag in metadata['tags']])
        toml_lines.append(f'tags = [**tags_str**]')

    # 布尔字段 - 小写 true/false
    toml_lines.append(f'draft = **str(metadata["draft"]).lower()**')

    # 描述 - 需要转义引号
    if metadata['description']:
        desc = metadata['description'].replace('"', '\\"')
        toml_lines.append(f'description = "**desc**"')

    toml_lines.append("+++")
    return "\n".join(toml_lines)

def extract_image_references(self, body: str) -> List[str]:
    """提取文章中的所有图片引用"""
    # 匹配 Obsidian Wiki-style: ![obsidian-hugo-complete-publishing-system-4.png](/tech/obsidian-hugo-complete-publishing-system-4.png)
    wiki_pattern = r'!\[\[([^\]]+)\]\]'
    wiki_images = re.findall(wiki_pattern, body)

    # 匹配标准 Markdown 本地图片: ![obsidian-hugo-complete-publishing-system-4.png](/tech/obsidian-hugo-complete-publishing-system-4.png)
    md_pattern = r'!\[([^\]]*)\]\((?!http)([^\)]+)\)'
    md_images = [match[1] for match in re.findall(md_pattern, body)]

    return wiki_images + md_images

def normalize_image_filename(self, filename: str) -> str:
    """标准化图片文件名"""
    # 处理空格：Mac mini.png → mac-mini.png
    if config['remove_spaces']:
        filename = filename.replace(' ', '-')

    # 转换为小写：Test.PNG → test.png
    if config['lowercase']:
        name, ext = os.path.splitext(filename)
        filename = name.lower() + ext.lower()

    return filename

def replace_image_links(self, body: str, image_mapping: Dict[str, str], category: str) -> str:
    """替换图片链接为 Hugo 格式"""
    result = body

    for original_name, new_name in image_mapping.items():
        # 替换 Wiki-style 链接
        wiki_pattern = rf'!\[\[**re.escape(original_name)**\]\]'
        hugo_link = f'![**new_name**](/**category**/{new_name})'
        result = re.sub(wiki_pattern, hugo_link, result)

        # 替换标准 Markdown 链接（保留原有 alt 文本）
        md_pattern = rf'!\[([^\]]*)\]\(**re.escape(original_name)**\)'
        hugo_link_with_alt = rf'![\1](/**category**/{new_name})'
        result = re.sub(md_pattern, hugo_link_with_alt, result)

    return result

$ python publish.py

============================================================
  Obsidian → Hugo Blog 自动发布工具
============================================================

🔍 正在扫描草稿...

📝 可用的草稿文件:

  [1] 实验室自动化：从传统到智能的转型之路.md (修改于: 2024-08-19 09:23)
  [2] tailscale-derp-guide.md (修改于: 2024-06-07 16:52)

选择要发布的草稿: 2

✅ 已选择: tailscale-derp-guide.md

📋 请提供发布信息:

文章标题 [Tailscale 完全指南]: Tailscale完全指南：从自建DERP服务器到Mac子网路由
选择分类:
  ❯ tech
    read
    life
    project

标签 (逗号分隔): Tailscale, DERP, Mac, 子网路由, 网络, 服务器部署
文章描述 (用于 SEO): 一篇关于如何自建Tailscale DERP服务器以及配置Mac作为子网路由的详细指南

🖼️  正在处理图片...
找到 3 张图片
✅ 复制图片: Mac mini.png -> mac-mini.png
✅ 复制图片: Pasted image 20230320223703.png -> pasted-image-20230320223703.png
✅ 复制图片: tailscale-diagram.png -> tailscale-diagram.png

📝 正在生成文章...

============================================================
✅ 发布完成！
============================================================

📍 文章位置: blog/content/posts/tech/2025-11-14_tailscale-derp-guide.md
📍 分类: tech
📍 标签: Tailscale, DERP, Mac, 子网路由, 网络, 服务器部署

💡 下一步:
   1. 同步: python sync.py
   2. 预览: cd blog && hugo server -D
   3. 部署: cd blog && git push

# 伪代码
for each file in all_files:
    if file exists only in Obsidian:
        action = "新增到 Hugo"
    elif file exists only in Hugo:
        action = "新增到 Obsidian"
    elif obsidian_mtime > hugo_mtime:
        action = "更新 Hugo"
    elif hugo_mtime > obsidian_mtime:
        action = "更新 Obsidian"
    else:
        action = "已同步，跳过"

Main/07 blog idea/
├── draft/
├── ready/
├── published/              # 扁平结构
│   ├── article-1.md
│   ├── article-2.md
│   └── ...
└── *.md

Main/07 blog idea/
├── draft/
├── ready/
├── published/              # 按分类组织
│   ├── tech/              # 技术类
│   ├── read/              # 阅读类
│   ├── life/              # 生活类
│   └── project/           # 项目类
└── *.md

def scan_files(self, directory: Path, category: str) -> Dict[str, Path]:
    """扫描指定目录下的文章文件"""
    files = {}
    category_dir = directory / category
    if category_dir.exists():
        for file in category_dir.glob("*.md"):
            if file.is_file():
                files[file.name] = file
    return files

def compare_files(self, obsidian_files: Dict[str, Path],
                  hugo_files: Dict[str, Path]) -> Tuple[List, List, List]:
    """
    比较 Obsidian 和 Hugo 的文件
    返回：(需要同步到 Hugo 的, 需要同步到 Obsidian 的, 冲突的)
    """
    to_hugo = []      # Obsidian 更新 → Hugo
    to_obsidian = []  # Hugo 更新 → Obsidian
    conflicts = []    # 两边都修改过的文件

    # Obsidian 中有但 Hugo 中没有，或 Obsidian 更新
    for filename, obs_path in obsidian_files.items():
        if filename not in hugo_files:
            to_hugo.append((filename, obs_path, None, 'new'))
        else:
            hugo_path = hugo_files[filename]
            obs_mtime = self.get_file_mtime(obs_path)
            hugo_mtime = self.get_file_mtime(hugo_path)

            # 时间差超过 1 秒才认为有修改
            time_diff = abs(obs_mtime - hugo_mtime)
            if time_diff > 1:
                if obs_mtime > hugo_mtime:
                    to_hugo.append((filename, obs_path, hugo_path, 'update'))
                else:
                    to_obsidian.append((filename, hugo_path, obs_path, 'update'))

    # Hugo 中有但 Obsidian 中没有
    for filename, hugo_path in hugo_files.items():
        if filename not in obsidian_files:
            to_obsidian.append((filename, hugo_path, None, 'new'))

    return to_hugo, to_obsidian, conflicts

def sync_file(self, source: Path, target: Path, action: str):
    """同步单个文件"""
    try:
        target.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(source, target)  # 保留文件元数据
        return True
    except Exception as e:
        print(f"❌ 同步失败 **source.name**: **e**")
        return False

def sync_category(self, category: str, direction: str = 'both') -> Dict:
    """
    同步指定分类的文章
    direction: 'to_hugo', 'to_obsidian', 'both'
    """
    print(f"\n📂 同步分类: **category**")
    print("-" * 60)

    # 扫描文件
    obsidian_files = self.scan_files(self.published_folder, category)
    hugo_files = self.scan_files(self.hugo_content, category)

    print(f"Obsidian: **len(obsidian_files)** 篇文章")
    print(f"Hugo Blog: **len(hugo_files)** 篇文章")

    # 比较文件
    to_hugo, to_obsidian, conflicts = self.compare_files(obsidian_files, hugo_files)

    stats = **
        'to_hugo': 0,
        'to_obsidian': 0,
        'skipped': 0,
        'failed': 0
    **

    # 同步到 Hugo
    if direction in ['to_hugo', 'both'] and to_hugo:
        print(f"\n📤 需要同步到 Hugo: **len(to_hugo)** 篇")
        for filename, source, target, action in to_hugo:
            action_text = "新增" if action == 'new' else "更新"
            target_path = self.hugo_content / category / filename
            if self.sync_file(source, target_path, action):
                print(f"  ✅ **action_text**: **filename**")
                stats['to_hugo'] += 1
            else:
                stats['failed'] += 1

    # 同步到 Obsidian
    if direction in ['to_obsidian', 'both'] and to_obsidian:
        print(f"\n📥 需要同步到 Obsidian: **len(to_obsidian)** 篇")
        for filename, source, target, action in to_obsidian:
            action_text = "新增" if action == 'new' else "更新"
            target_path = self.published_folder / category / filename
            if self.sync_file(source, target_path, action):
                print(f"  ✅ **action_text**: **filename**")
                stats['to_obsidian'] += 1
            else:
                stats['failed'] += 1

    return stats

# 查看同步状态
python sync.py --status

# 双向同步
python sync.py
python sync.py --direction both

# 单向同步
python sync.py --direction to_hugo
python sync.py --direction to_obsidian

# 预览模式
python sync.py --dry-run

# 交互式
python sync.py -i

$ python sync.py --direction to_obsidian

============================================================
  Obsidian ↔ Hugo Blog 双向同步工具
============================================================
同步方向: Hugo → Obsidian

📂 同步分类: tech
------------------------------------------------------------
Obsidian: 0 篇文章
Hugo Blog: 20 篇文章

📥 需要同步到 Obsidian: 20 篇
  ✅ 新增: ai-agent-seo-optimization.md
  ✅ 新增: tailscale-derp-guide.md
  ✅ 新增: github-to-cloudflare-pages.md
  ... (共 20 篇)

📂 同步分类: read
------------------------------------------------------------
Obsidian: 0 篇文章
Hugo Blog: 5 篇文章

📥 需要同步到 Obsidian: 5 篇
  ✅ 新增: Getting things done.md
  ... (共 5 篇)

============================================================
✅ 同步完成！
============================================================

📊 同步统计:
  📤 Obsidian → Hugo: 0 篇
  📥 Hugo → Obsidian: 37 篇

总计: 37 篇文章已同步

# 同步回 Obsidian
$ python sync.py --direction to_obsidian

📂 同步分类: tech
📥 需要同步到 Obsidian: 1 篇
  ✅ 更新: obsidian-to-hugo-automation.md

# 双向同步
$ python sync.py

📂 同步分类: tech
Obsidian: 20 篇文章
Hugo Blog: 21 篇文章

📥 需要同步到 Obsidian: 1 篇
  ✅ 新增: new-article.md

📂 同步分类: read
Obsidian: 6 篇文章
Hugo Blog: 5 篇文章

📤 需要同步到 Hugo: 1 篇
  ✅ 新增: new-book-review.md

unsplash:
  access_key: "YOUR_ACCESS_KEY_HERE"
  enabled: true

$ python publish.py

💡 文章中没有图片，可以添加 Unsplash 封面图
🔍 正在 Unsplash 搜索封面图: "programming"...
✅ 找到 10 张图片

📸 可选图片:
  [1] Modern workspace with laptop - by John Doe
  [2] Abstract technology background - by Jane Smith
  [3] Code on screen - by Developer X
  ...

选择图片 (1-10, 0=跳过): 1

✅ 封面图已下载: blog/static/tech/cover.jpg
📝 已添加摄影师署名

# 发布前自动检查
./check_sensitive.sh

python publish.py \
  -f "ready/article.md" \
  -t "文章标题" \
  -c tech \
  --tags "标签1,标签2,标签3" \
  -s "article-slug" \
  -d "文章描述（100-160字符）"

~/.claude/
└── skills/
    └── obsidian-hugo-publisher/
        ├── SKILL.md                 # 主 Skill 定义
        ├── WORKFLOW.md              # 发布工作流
        ├── COMMANDS.md              # 命令参考
        ├── publish.py               # 发布脚本
        ├── sync.py                  # 同步脚本
        ├── unsplash_cover.py        # Unsplash 封面图模块
        ├── publish_config.yaml      # 配置文件
        └── check_sensitive.sh       # 敏感信息检查脚本

## 当用户请求发布文章时

### 步骤 1：理解用户意图
- 如果用户指定了文件，使用该文件
- 如果用户说"这篇文章"，使用当前打开的文件
- 如果没有指定，扫描 ready/ 目录并让用户选择

### 步骤 2：安全检查（必须执行）
- 运行：`.claude/skills/obsidian-hugo-publisher/check_sensitive.sh`
- 检查是否包含敏感信息：
  - API keys, tokens, passwords
  - 公司名称（BASF、巴斯夫）
  - IP 地址、服务器信息
- 如果发现敏感信息，**停止发布**并提示用户

### 步骤 3：提取或询问元数据
- 尝试从文章内容自动提取：
  - 标题（从 YAML Front Matter 或第一个 # 标题）
  - 现有标签
  - 分类（从文件路径或 project 字段推断）
- 如果缺失，智能询问用户：
  - 标题（必需）
  - 分类：tech/read/life/project
  - 标签（逗号分隔）
  - SEO 描述

### 步骤 4：执行发布
运行发布命令（使用 skill 目录下的脚本）：
```bash
python .claude/skills/obsidian-hugo-publisher/publish.py \
  -f "ready/article.md" \
  -t "文章标题" \
  -c tech \
  --tags "标签1,标签2,标签3" \
  -d "文章描述"

python .claude/skills/obsidian-hugo-publisher/sync.py

### 使用体验演示

#### 场景 1：发布指定文章

#### 场景 2：一句话完整发布

#### 场景 3：智能错误处理

### 对比：传统方式 vs Agent Skills

| 维度           | 传统 Python 脚本                  | Agent Skills            |
| -------------- | --------------------------------- | ----------------------- |
| **触发方式**   | `python publish.py -f ... -t ...` | "帮我发布文章"          |
| **参数记忆**   | 需要记忆所有参数                  | 无需记忆，自然对话      |
| **元数据输入** | 必须在命令行指定                  | 智能提取 + 交互式补充   |
| **错误处理**   | 手动查看错误信息并修复            | 自动检测 + 给出修复建议 |
| **流程遗漏**   | 容易忘记某个步骤（如 sync）       | 自动执行完整流程        |
| **灵活性**     | 固定参数                          | 理解多种表述方式        |
| **学习成本**   | 需要学习命令行参数                | **零学习成本**          |
| **体验**       | 工具化、机械                      | 对话式、自然            |

### 技术实现细节

#### Skill 如何调用 Python 脚本

Claude Agent 通过 `Bash` 工具执行系统命令：
- 使用 Bash 工具运行 `python .claude/skills/obsidian-hugo-publisher/publish.py` 并传递参数
- 解析命令输出，提取成功/失败信息
- 如果失败，分析错误信息并给出建议

**路径设计：** 所有脚本都放在 skill 目录下，确保：
- ✅ 便于移植（只需复制一个文件夹）
- ✅ 便于版本管理
- ✅ 避免路径混乱

#### Skill 如何智能提取元数据

1. 使用 Read 工具读取文章内容
2. 使用正则表达式解析 YAML Front Matter
3. 提取第一个 # 标题作为备选标题
4. 分析内容关键词，推荐相关标签
5. 提取第一段作为描述候选

#### Skill 如何处理用户输入

Claude 的自然语言理解能力：
- "发布这篇文章" → 使用当前打开的文件
- "发布 XXX 文章" → 在 ready/ 目录搜索标题匹配的文件
- "发布最新的文章" → 按修改时间排序，选择最新的
- "发布关于 AI 的文章" → 搜索标题/内容包含 "AI" 的文章

---

## 完整使用指南

### 方式 1：使用 Agent Skills（★推荐★）

这是最简单的方式，只需要和 Claude 对话即可完成整个发布流程。

#### 最简单的发布

Claude 会：
1. 扫描 ready 目录
2. 让你选择要发布的文章
3. 自动检查敏感信息
4. 智能提取元数据（标题、标签等）
5. 询问缺失的信息（分类、描述）
6. 执行发布和同步
7. 询问是否需要预览或部署

**全程只需要回答几个简单问题，其他都自动完成！**

#### 指定文章发布

Claude 会自动搜索标题匹配的文章并发布。

#### 完整发布并部署

Claude 会执行完整流程：发布 → 同步 → 构建 → 部署，全自动。

**对比：**
- **Agent Skills 方式**：1 句话，3-5 次交互，零学习成本
- **传统方式**：5 个命令，需要记忆所有参数

---

### 方式 2：使用 Python 脚本（传统方式）

如果不想使用 Agent Skills，也可以直接运行 Python 脚本：

#### 1️⃣ 安全检查

```bash
./check_sensitive.sh

python publish.py \
  -f "ready/article.md" \
  -t "文章标题" \
  -c tech \
  --tags "标签1,标签2,标签3" \
  -d "文章描述"

python sync.py

cd blog
hugo server -D

cd blog
hugo
git add .
git commit -m "发布新文章：[文章标题]"
git push origin main

# 发布单篇文章（交互式）
python publish.py

# 查看待发布队列
ls -lh "Main/07 blog idea/ready/"

# 查看已发布文章
ls -lh "Main/07 blog idea/published/"

# 双向同步（推荐，发布后必须运行）
python sync.py

# 查看同步状态（不执行同步）
python sync.py --status

# 单向同步：Hugo → Obsidian
python sync.py --direction to_obsidian

# 单向同步：Obsidian → Hugo
python sync.py --direction to_hugo

# 交互式同步
python sync.py --interactive

# 预览模式（查看会同步哪些文件）
python sync.py --dry-run

# 本地预览（包含草稿）
cd blog && hugo server -D

# 构建静态站点
cd blog && hugo

# 提交并推送
cd blog && git add . && git commit -m "发布新文章" && git push

# 1. 将文章从 draft/ 移动到 ready/
mv "Main/07 blog idea/draft/my-article.md" "Main/07 blog idea/ready/"

# 2. 安全检查（必做）
./check_sensitive.sh

# 3. 发布文章
python publish.py
# 选择文章，填写元数据...

# 4. 同步到 Obsidian（重要）
python sync.py

# 5. 预览
cd blog && hugo server -D

# 6. 部署
cd blog
hugo
git add .
git commit -m "发布新文章：我的文章标题"
git push

python sync.py --direction to_obsidian

# 查看待发布队列
ls -lh "Main/07 blog idea/ready/"

# 查看同步状态
python sync.py --status

# 查看 Hugo 文章
ls -lh "blog/content/posts/tech/"

time_diff = abs(obs_mtime - hugo_mtime)
if time_diff > 1:  # 只有差异大于 1 秒才认为有修改
    # 进行同步

target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(source, target)

shutil.copy2(source, target)  # 保留修改时间等元数据

from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class SyncHandler(FileSystemEventHandler):
    def on_modified(self, event):
        # 自动触发同步
        pass

# 命令配置
cd /Users/huashan/Documents/Obsidian && python publish.py

# 绑定快捷键
Cmd+Shift+P

from PIL import Image

def compress_image(source_path: Path, target_path: Path, quality: int = 85):
    """压缩图片"""
    with Image.open(source_path) as img:
        # 转换 RGBA 为 RGB（PNG → JPG）
        if img.mode == 'RGBA':
            img = img.convert('RGB')

        # 压缩并保存
        img.save(target_path, optimize=True, quality=quality)

~/.claude/
└── skills/
    └── obsidian-hugo-publisher/
        ├── SKILL.md                 # 主 Skill 定义
        ├── WORKFLOW.md              # 发布工作流
        ├── COMMANDS.md              # 命令参考
        ├── publish.py               # 发布脚本
        ├── sync.py                  # 同步脚本
        ├── unsplash_cover.py        # Unsplash 封面图模块
        ├── publish_config.yaml      # 配置文件
        └── check_sensitive.sh       # 敏感信息检查脚本