张洪Heo博客助手 - HTTP API 搜索/热门/归档/标签/友链

Skill: zhheo-blog-tools

通过 HTTP API 访问张洪Heo博客（https://blog.zhheo.com），无需打开浏览器。

触发词：张洪Heo、博客、博主、张洪、Heo

基础 URL：https://blog.zhheo.com

场景路由

---

API 参考

1. 全文搜索（主路径）

GET /api/search/search.php?q=关键词&limit=10&page=1

• 搜索范围：标题 + 正文 + 标签 + 分类
• 多关键词用空格分隔，AND 逻辑（所有词都必须命中）
• limit：1–50，默认 10；page：页码，默认 1
• 无需认证，服务端已做分级排序，直接调用即可

分级相关度（服务端内置）：

• 每个关键词命中：+10
• 标题命中：+50
• 正文/标签/分类命中：+5

响应示例：

{
  "success": true,
  "hits": [
    { "title": "文章标题", "path": "p/xxx.html", "cover": "https://...", "score": 65 }
  ],
  "total": 42,
  "query": "关键词",
  "page": 1,
  "limit": 10
}

完整 URL 拼接：https://blog.zhheo.com/ + path

curl 示例：

curl -s 'https://blog.zhheo.com/api/search/search.php?q=OpenClaw&limit=5'

---

2. 归档浏览

GET /api/archives/posts.php?year=2026&limit=10&page=1
GET /api/archives/posts.php?meta=years

文章列表响应：

{
  "success": true,
  "year": "2026",
  "page": 1,
  "limit": 10,
  "total": 150,
  "items": [
    {
      "title": "...",
      "url": "https://blog.zhheo.com/p/xxx.html",
      "cover": "https://...",
      "year": "2026",
      "date": "2026-07-28",
      "dateLabel": "2026年7月28日",
      "categories": ["设计"],
      "primaryCategory": "设计"
    }
  ]
}

---

3. 热门文章

GET /api/umami/hot.php?period=day&limit=10

必须携带 Referer 头，否则返回 403：

Referer: https://blog.zhheo.com/

curl 示例：

curl -s -H 'Referer: https://blog.zhheo.com/' \
  'https://blog.zhheo.com/api/umami/hot.php?period=day&limit=5'

---

4. 标签 / 分类 / 页面

标签： GET /api/tags.json
分类： GET /api/categories.json
非文章页面： GET /api/pages.json

常用页面：/about/、/link/、/equipment/、/rss/、/skill/、/hot/、/must-read/

---

5. 友链搜索

GET /api/friendlink/friendlink.json

在返回数据的 link_list[].name 中按关键词本地过滤。

---

6. 读取文章正文

1. 通过 search.php 或 archives/posts.php 获取文章 path / url
2. web_fetch 或 curl 获取页面 HTML
3. 提取正文：#article-container → #post-body → #content-inner → article
4. 超过 6000 字截断并注明

---

7. RSS 订阅

GET /rss.xml

建议每日检查一次，监控最新文章。

---

完整流程示例

搜索文章

1. GET /api/search/search.php?q=关键词&limit=5
2. 返回 hits 中的 title 和完整 URL（https://blog.zhheo.com/ + path）
3. 若用户需要正文，继续 web_fetch 文章页面

今日热门

1. GET /api/umami/hot.php?period=day&limit=10，携带 Referer: https://blog.zhheo.com/
2. 返回 items（含 title、url、visitors、cover）

按标签/分类推荐

1. GET /api/tags.json 或 /api/categories.json
2. GET /api/search/search.php?q=标签名&limit=5

最新文章

1. GET /api/archives/posts.php?year=all&limit=10&page=1

读某篇文章

1. search.php 或 archives 定位 URL
2. web_fetch 提取正文后回答

博主装备

1. web_fetch https://blog.zhheo.com/equipment/

博主项目

1. GET /api/search/search.php?q=我的项目&limit=10
2. 或 archives 筛选 categories 含「我的项目」

友链查询

1. GET /api/friendlink/friendlink.json，按 name 过滤

---

注意事项

• 搜索主路径：优先 search.php
• Referer 要求：/api/umami/hot.php 必须带 Referer: https://blog.zhheo.com/
• URL 规范：使用 API 返回的原始 path，禁止自行编造 slug
• 不在 skill 范围内：音乐控制、截图、评论填入等浏览器专属能力，引导用户访问 https://blog.zhheo.com