一、 为什么要自动命名

在 Ghost 博客系统中，URL 路由的生成规则存在一个针对中文用户的原生缺陷：系统会自动将非拉丁字符（中文标题）强制转换为极长的拼音或十六进制 UTF-8 编码拼接字符串。

例如，标题《国内无需端口号直连自建服务器》会被系统自动转换为类似 guoneiwuxuduankouhaozhilianzijiandefuwuqi 或包含 %E5 乱码的 URL。

这种 URL 结构在技术 SEO 层面是毁灭性的：

1. 语义权重丧失： 搜索引擎爬虫无法高效提取冗长拼音或十六进制字符中的关键词。
2. 点击率骤降： 用户在搜索结果页中看到极长的无逻辑 URL 会判定为垃圾网站，从而拒绝点击。
3. 极易触发死链： 长链接在社交平台或论坛传播时极易被截断。

最佳的解决方案是手动将 URL 替换为 2-5个英文核心关键词组合。通过 Ghost 的高度开放性，我们可以调用轻量级大语言模型来完成这个任务。本文选用了 L M Studio+Qwen3.5 2B Q4来完成，事实证明，对于简单任务，纯 CPU 推理速度完全足够。

二、 方法与排坑

由于 Ghost 的核心 URL 生成机制被硬编码在 @tryghost/string 模块中，直接修改容器内的底层代码会在后续镜像升级时被全数覆盖。因此，采用**Ghost 的 WebHooks**是最佳方案。

本方案在 Windows 宿主机运行一个 Python Flask 中间件，监听 Ghost 容器发出的 Webhook，提取中文标题，调用本地 LM Studio 部署的大模型生成英文短链，最后通过 Admin API 回写数据库。

在实施过程中，需要排除以下四个核心技术暗坑：

1. 拦截死循环陷阱

如果 Webhook 监听了 Post created 或 Post edited 事件，脚本回写 URL 的动作会再次触发编辑事件，导致无限死循环。

• 解决方案： 严格将触发条件设定为 Post published（文章发布）。不仅物理切断了死循环，且符合 SEO 铁律：URL 仅在首次发布时确定，后续无论如何修改文章标题，URL 必须锁死不变。

2. 本地小模型的指令依从性崩塌

本地运行的轻量级模型在处理 Zero-shot（零样本）提示词时，容易忽略“提取核心词”的指令，退化为字对字的整句直翻（例如将“这绝对是个严重的问题”翻译为 this-mad-absolute-severe-problem）。

• 解决方案： 强制注入高质量的 Few-Shot（少样本）提示词，涵盖技术类和随笔类标题，利用上下文强制对齐模型的输出格式。

3. Python 依赖库混淆 (AttributeError: 'module' object has no attribute 'encode')

在生成 Ghost API 需要的鉴权 Token 时，常见的坑是安装了错误的包。Python 生态中 jwt 和 PyJWT 会发生冲突。

• 解决方案： 必须使用 pip uninstall jwt pyjwt -y 彻底清理环境，然后仅执行 pip install PyJWT。

4. API 301 重定向导致鉴权请求头丢失 (NoPermissionError)

如果 Python 脚本向 Ghost 的 http://localhost:2368 发起请求，而 Ghost 全局配置的 URL 是 https://your-domain.com，Ghost 会返回 301 重定向。Python 的 requests 库在跟随跨域/跨协议重定向时，出于安全规范会自动剥离 Authorization 请求头，导致最终请求鉴权失败。同时，如果本机开启了代理也可能导致请求失败。

• 解决方案： 脚本中的 GHOST_ADMIN_API_URL 必须严格对齐 Ghost 后台显示的完整公网 URL；设置本机代理规则绕过你的网站。

三、 完整代码实现

在宿主机建立 Python 环境，安装依赖：

Bash

pip install flask requests PyJWT flask

保存文末代码为 ghost_slug_agent.py（注意替换你的 API Key 和公网域名）。

四、 部署

1. 在 Ghost 后台 Settings -> Integrations 创建自定义 Integration，获取 Admin API Key。
2. 在该 Integration 页面添加 Webhook：
   • Event: Post published
   • Target URL: http://host.docker.internal:5000/webhook/post-published (由于 Ghost 运行在 Docker 中，必须使用此专用 DNS 解析至 Windows 宿主机端口)。
3. 运行 Python 脚本。正常使用 Ghost 编辑器写作，点击发布的瞬间，底层将自动完成高权重英文 URL 的覆写。如果以后想要修改标题并重新发布即可在保留初始发布日期的情况下重置URL。但这样会导致搜索引擎的缓存全部404。确保不要对已经发布了一段时间的文章这么做。

import time
import jwt
import requests
import threading
from flask import Flask, request, jsonify

app = Flask(__name__)

# ================= 配置区域 =================
# 1. Ghost Admin API 配置
GHOST_ADMIN_API_URL = 'https://你的公网域名' # 必须与 Ghost 后台保持绝对一致，避免 301 重定向
GHOST_ADMIN_API_KEY = 'YOUR_ID:YOUR_SECRET' # 替换为在 Ghost 后台生成的 API 密钥

# 2. LM Studio 本地 API 配置
LM_STUDIO_API_URL = 'http://127.0.0.1:1234/v1/chat/completions'
# ============================================

def generate_ghost_token():
    """生成 Ghost Admin API 需要的 JWT Token"""
    id, secret = GHOST_ADMIN_API_KEY.split(':')
    iat = int(time.time())
    header = {'alg': 'HS256', 'typ': 'JWT', 'kid': id}
    payload = {'iat': iat, 'exp': iat + 5 * 60, 'aud': '/admin/'}
    return jwt.encode(payload, bytes.fromhex(secret), algorithm='HS256', headers=header)

def generate_slug_via_llm(title):
    """调用本地 LM Studio 生成英文短链 (Few-Shot 强化版)"""
    payload = {
        "model": "local-model",
        "messages": [
            {
                "role": "system", 
                "content": "You are a strict SEO URL slug generator. Rule 1: Extract ** ONLY 2 to 5 ** core noun keywords from the title. Rule 2: Remove ALL stop words (how, to, about, this, a, etc.), adjectives, and emotional words. Rule 3: Output ONLY lowercase English words separated by hyphens. ** NO punctuation. NO explanations**."
            },
            # --- 高质量 Tech (技术类) 样本 ---
            {"role": "user", "content": "深入剖析多智能体 AI 剧本创作系统的底层架构"},
            {"role": "assistant", "content": "multi-agent-screenwriting-architecture"},
            
            {"role": "user", "content": "家用服务器 AMD 9950X 装机实录与系统性能优化"},
            {"role": "assistant", "content": "home-server-build-optimization"},

            {"role": "user", "content": "基于大模型的音频分离技术在编曲工作流中的应用"},
            {"role": "assistant", "content": "llm-audio-separation-workflow"},

            # --- 高质量 Essay (随笔类) 样本 ---
            {"role": "user", "content": "雨后的旧书店：在霉味与墨香中捕捉旧时光的碎片"},
            {"role": "assistant", "content": "old-bookstore-memories"},

            {"role": "user", "content": "凌晨三点的城市漫游：那些被日光掩盖的孤独与温柔"},
            {"role": "assistant", "content": "midnight-city-wander"},

            {"role": "user", "content": "关于社交恐惧症的一点自白：如何在高频率互动中保持自我"},
            {"role": "assistant", "content": "social-anxiety-reflection"},

            {"role": "user", "content": "独居生活随笔：关于养猫的长远承诺与情感羁绊"},
            {"role": "assistant", "content": "living-alone-pet-commitment"},
            
            # --- 样本结束，处理真实输入 ---
            {"role": "user", "content": title}
        ],
        "temperature": 0.1,
        "max_tokens": 30
    }
    try:
        response = requests.post(LM_STUDIO_API_URL, json=payload, timeout=15)
        response.raise_for_status()
        slug = response.json()['choices'][0]['message']['content'].strip()
        # 二次清洗：只保留字母、数字和连字符
        slug = ''.join(e for e in slug if e.isalnum() or e == '-')
        return slug
    except Exception as e:
        print(f"\n[错误] 调用 LM Studio 失败: {e}")
        return None

@app.route('/webhook/post-published', methods=['POST'])
def handle_post_published():
    data = request.json
    try:
        post = data['post']['current']
        post_id = post['id']
        title = post['title']
        updated_at = post['updated_at']
        current_slug = post['slug']
    except KeyError:
        return jsonify({"status": "ignored", "reason": "invalid payload"}), 400

    print(f"\n[Webhook 触发] 侦测到文章发布: {title}")

    new_slug = generate_slug_via_llm(title)
    if not new_slug or new_slug == current_slug:
        return jsonify({"status": "skipped"}), 200

    print(f"[LLM 翻译] 准备将 URL 更新为: {new_slug}")

    # 调用 Ghost API 覆写 URL
    token = generate_ghost_token()
    headers = {
        'Authorization': f'Ghost {token}',
        'Content-Type': 'application/json',
        'Accept-Version': 'v5.0'
    }
    update_payload = {
        "posts": [{
            "id": post_id,
            "slug": new_slug,
            "updated_at": updated_at
        }]
    }

    try:
        update_url = f"{GHOST_ADMIN_API_URL}/ghost/api/admin/posts/{post_id}/"
        res = requests.put(update_url, json=update_payload, headers=headers)
        res.raise_for_status()
        print(f"[成功] 文章已更新为纯英文 URL: {new_slug}\n")
        return jsonify({"status": "success", "new_slug": new_slug}), 200
    except requests.exceptions.HTTPError as e:
        print(f"\n[错误] 更新 Ghost 失败: {res.text}")
        return jsonify({"status": "error"}), 500

def console_tester():
    """独立的控制台测试线程"""
    time.sleep(1)
    print("\n" + "="*50)
    print("🤖 LLM Slug 测试终端已启动")
    print("随时输入中文标题并回车进行测试 (输入 q 退出)")
    print("="*50 + "\n")
    
    while True:
        try:
            title = input("请输入测试标题 > ")
            if title.strip().lower() == 'q':
                break
            if title.strip():
                print("正在请求本地大模型...")
                result = generate_slug_via_llm(title)
                print(f"✅ 生成结果: {result}\n")
        except KeyboardInterrupt:
            break

if __name__ == '__main__':
    # 启动控制台测试线程
    tester_thread = threading.Thread(target=console_tester, daemon=True)
    tester_thread.start()
    
    # 启动 Flask Webhook 监听服务
    app.run(host='0.0.0.0', port=5000)