---
name: gzh-public-api
description: 当 agent 需要通过稳定的 HTTP API 读取这个微信公众号系统的公开数据时使用。优先使用这些接口完成公众号搜索、公众号列表、文章列表和文章详情读取。除非用户明确要求后台管理，否则不要使用 admin、task、cron 或账号配置相关路由。
---

# GZH 公开 API

优先使用用户提供的部署地址；如果用户给了 `https://xxx/skill.md` 这样的链接，那么默认将 `https://xxx` 作为 `BASE_URL`。只有在明确知道本地开发地址时，才使用本地地址，不要默认写 `127.0.0.1`。

```bash
BASE_URL="https://你的域名"
```

如果用户没有提供 URL，但当前环境已经明确有可访问站点，也应优先使用那个站点地址。

## 推荐流程

1. 用 `/api/official-accounts?search=...` 搜索公众号
2. 或用 `/api/accounts/list` 浏览已缓存的公众号列表
3. 用 `/api/official-accounts/{fakeid}/articles` 读取某个公众号的文章列表
4. 用 `/api/articles/{appmsgid}?withContent=true` 读取单篇文章

说明：
- 常规读取优先用 `/api/official-accounts?search=...`，不要优先用 `/api/accounts/search`。
- 文章列表优先用 `/api/official-accounts/{fakeid}/articles`，分页行为更稳定。
- 如果文章正文缺失，再次请求文章详情并带上 `withContent=true`。
- 默认不要直接抓取 `mp.weixin.qq.com` 文章链接做正文提取，直接访问可能只会拿到验证页。

## 可用公开接口

### 1. 搜索公众号

```bash
curl -s "$BASE_URL/api/accounts/search" \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"AI","page":1,"pageSize":20}'
```

说明：
- 请求方法是 `POST`。
- 返回通常包含 `success`、`data`、`source`、`total`。
- `forceSync: true` 会触发上游刷新，速度更慢。
- 某些路径下返回条数可能多于请求的 `pageSize`。除非明确需要这个接口，否则优先用 `/api/official-accounts?search=...`。

### 2. 获取缓存公众号列表

```bash
curl -s "$BASE_URL/api/accounts/list?page=1&pageSize=12&sortBy=lastSyncedAt&sortOrder=desc"
```

常用筛选：
- `serviceType=1|2`
- `verifyStatus=0|2`

### 3. 查询单个公众号或按关键字搜索

```bash
curl -s "$BASE_URL/api/official-accounts?fakeid=FAKEID"
curl -s "$BASE_URL/api/official-accounts?search=AI"
```

### 4. 获取某个公众号的文章列表

支持两种分页模式：`page`（页码偏移）和 `before`（游标），二选一。`pageSize` 固定 20。

```bash
# 页码模式（默认第 1 页）
curl -s "$BASE_URL/api/official-accounts/FAKEID/articles?page=1"

# 游标模式（获取指定时间之前的 20 篇）
curl -s "$BASE_URL/api/official-accounts/FAKEID/articles?before=2024-03-01T12:00:00Z"
```

返回结构中的 `pagination` 字段：
- `total` / `totalPages`：基于本地已缓存文章数计算，只能翻到已缓存的页。
- `wechatTotal`：微信官方文章总数，仅供展示。
- `nextCursor`：本页最后一篇文章的 `create_time`，传给下次请求的 `before` 参数即可翻到下一页。

说明：
- 服务端自动决定是否从微信同步：首次访问自动拉取，数据过期（>6h）后台静默刷新，其他情况返回缓存。
- 调用方无需关心同步参数，直接请求即可。
- 推荐使用游标模式（`before`）遍历，分页结果更稳定；页码模式在新文章插入后可能有轻微漂移。

### 5. 获取全部缓存文章

```bash
curl -s "$BASE_URL/api/articles/list?page=1&pageSize=12&sortOrder=desc"
```

常用筛选：
- `keyword=...`
- `fakeid=...`
- `hasContent=true`
- `today=true`
- `recentDays=true`

### 6. 读取单篇文章

```bash
curl -s "$BASE_URL/api/articles/APPMSGID"
curl -s "$BASE_URL/api/articles/APPMSGID?withContent=true"
```

说明：
- `withContent=true` 会在正文缺失时触发异步抓取。
- 返回中通常包含 `article`、`hasContent`、`isFetching`、`fetchFailed`。
- 如果 `hasContent` 为 `false` 且 `isFetching` 为 `true`，稍等后再次请求同一接口。
- 返回里的 `link` 适合作为给用户的参考原文链接，不适合作为默认提取路径。

## 使用规则

- 优先使用上面列出的公开读取接口。
- 普通读取场景不要调用 `/api/admin/*`、`/api/tasks*`、`/api/cron/*` 或 `/api/accounts`。
- 除非用户明确要求刷新，否则 `source: "cache"` 可以视为可接受结果。
- 如果返回 `success: false`，直接转述 API 错误，不要自行猜测。
- 如果要查文章详情但还没有 `appmsgid`，先调用文章列表接口。
- 如果带 `withContent=true` 重试后仍拿不到正文，要明确告诉用户公开 API 当前没有缓存正文，并附上原始 `link`。