> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 简报端点

> 读取、分享、渲染并分页 AI 生成的 World Monitor 每日全球情报简报——涵盖公开分享链接、轮播卡片、分享 URL 生成、订阅推送与嵌入端点的完整参考，适合将简报无缝接入你的网站、新闻邮件、Slack 频道、Discord 服务器、企业门户或自定义仪表盘展示。

WorldMonitor 在 Railway 上为每个用户生成情报简报，将每一期存储在 Redis 的 `brief:{userId}:{issueSlot}` 中，并在 `brief:latest:{userId}` 写入最新指针，暴露以下路由用于仪表盘回读、公开分享以及 Telegram/Slack 轮播渲染。默认节奏为每日，但每条告警规则的 `digestMode` 可调度每日、每日两次或每周的版本。

关于来源选择、过滤、去重、LLM 接地和偏见控制，请参见 [新闻摘要与简报方法论](/zh/methodology/news-digest-and-briefing)。

<Info>
  所有读取路由都需要有效的 Clerk 会话和 PRO 层级，公开分享路由（`/api/brief/public/{hash}`）除外。
</Info>

## 最新简报（已认证）

### `GET /api/latest-brief`

返回调用者最近生成简报的摘要，如果所请求/当前时段尚未生成简报，则返回 `{ status: "composing" }`。

| 状态     | 响应                                                                                        |
| ------ | ----------------------------------------------------------------------------------------- |
| 200 OK | `{ status: "ready", issueDate, issueSlot, dateLong, greeting, threadCount, magazineUrl }` |
| 200 OK | `{ status: "composing", issueDate, issueSlot? }` — 当前/所请求时段尚无简报                           |
| 401    | 缺失/无效的 Clerk JWT                                                                          |
| 403    | `pro_required`                                                                            |
| 503    | `BRIEF_URL_SIGNING_SECRET` 未配置                                                            |

`issueDate` 仍是显示/日期字段（`YYYY-MM-DD`）。`issueSlot` 是冻结的版本键（`YYYY-MM-DD-HHMM`），用于 Redis 查找和 HMAC 绑定；它出现在 ready 响应中，以及显式请求时段的未命中响应中。`magazineUrl` 针对 `{userId, issueSlot}` 重新签名，因此仅对已认证的所有者有效。

### `GET /api/brief/{userId}/{issueSlot}`

`issueSlot`（`YYYY-MM-DD-HHMM`）的完整杂志阅读器。需要 HMAC 签名 URL。时段格式允许两次同日摘要投递产生不同的冻结版本。

## 分享

### `POST /api/brief/share-url?slot=YYYY-MM-DD-HHMM`

为调用者在 `slot` 的简报物化一个公开分享指针。若省略 slot，该路由解析 `brief:latest:{userId}`。幂等 — hash 是 `{userId, issueSlot, BRIEF_SHARE_SECRET}` 的纯函数。

| 状态  | 响应                                       |
| --- | ---------------------------------------- |
| 200 | `{ shareUrl, hash, issueSlot }`          |
| 400 | `invalid_slot_shape` / `invalid_payload` |
| 401 | `UNAUTHENTICATED`                        |
| 403 | `pro_required`                           |
| 404 | `brief_not_found` — 阅读器无法分享不存在的内容        |
| 503 | `service_unavailable`                    |

### `GET /api/brief/public/{hash}`

**无需认证**的公开读取，用于之前分享的简报。该 hash 解析为 `brief:public:{hash} → {userId, issueSlot}` Redis 指针；如果不存在，则该简报从未被分享。分享指针是惰性写入的（在分享时，而非生成时）。

## 轮播（社交媒体图片）

### `GET /api/brief/carousel/{userId}/{issueSlot}/{page}.png`

服务器渲染的简报 PNG 页面（`page` = 1..N），用于 Telegram `sendMediaGroup`、Slack `chat.postMessage`、LinkedIn 等。

* 通过 `@resvg/resvg-js` 及捆绑的 Linux 原生绑定渲染。
* `Content-Type: image/png`，1080×1350（4:5 竖版）。
* 不设门禁 — 使用 HMAC 签名的路径作为能力凭证。

## 辅助

### `GET /api/story?date=YYYY-MM-DD`

用于分享简报的公开只读"故事视图"（Web 阅读器）。SEO 友好的 HTML 响应。

### `GET /api/og-story?date=YYYY-MM-DD`

`/api/story` 的 Open Graph 预览图。返回 `image/png`，激进缓存。

### `POST /api/chat-analyst`

仪表盘内"询问分析师"助手的流式聊天端点。接收用户提示+近期信号上下文；返回 SSE token。

* 认证：Clerk JWT + PRO
* 流式：`text/event-stream`
* 后端：`intelligence/v1/chat-analyst-*` 处理器组合上下文+提示

### `POST /api/widget-agent`

嵌入式 widget iframe 使用的单次完成端点。通过 `X-WorldMonitor-Key`（合作伙伴密钥）认证。按密钥限流。