123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
用 Cloudflare Workers（也可用于 Pages Functions）实现：
|
||
|
||
- KV 作为数据库：以文章相对 URL 存摘要内容
|
||
- Workers AI 负责生成摘要
|
||
- 纯静态页面（HTML + JS）：抽取指定元素（例如 `.post`）的正文，调用 API 生成/读取摘要并展示
|
||
- 内置 4 种摘要风格：`tldr` / `bullets` / `outline` / `keywords`
|
||
|
||
## 目录结构
|
||
|
||
- `src/worker.ts`：Workers API（KV 缓存 + Workers AI 生成）
|
||
- `public/index.html`：演示页面（静态）
|
||
- `public/summary.js`：前端抽取正文 + 请求摘要 + 渲染
|
||
- `public/summary.css`：几种风格的 UI 设计
|
||
|
||
## 本地开发（Pages）
|
||
|
||
1) 安装依赖
|
||
|
||
```bash
|
||
npm i
|
||
```
|
||
|
||
2) 本地启动（带本地 KV/AI 绑定）
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
打开 Wrangler 输出的本地地址，访问 `/` 即可看到 demo。
|
||
|
||
> 说明：`npm run dev` 默认使用 `wrangler pages dev public --kv KV --ai AI ...`，KV 会持久化到 `.wrangler/state`。
|
||
|
||
## 部署（Pages）
|
||
|
||
```bash
|
||
npm run deploy
|
||
```
|
||
|
||
在 Cloudflare Pages 项目设置里添加绑定：
|
||
|
||
- KV Namespace：变量名 `KV`
|
||
- AI：变量名 `AI`
|
||
- 环境变量：`MODEL`（可选，默认 `@cf/meta/llama-3.1-8b-instruct`）
|
||
|
||
> 注意：Pages Functions 也是跑在 Workers Runtime 上，调用 `/api/*` 仍会产生函数调用次数；本项目已用 KV 做缓存，只有首次/内容变化才会触发 AI 生成。
|
||
|
||
部署后：
|
||
|
||
- 静态页面：`/`
|
||
- API：
|
||
- `GET /api/styles`：返回可用风格
|
||
- `GET /api/summary?url=/post/xxx&style=tldr`：读取 KV 缓存（不存在返回 404）
|
||
- `POST /api/summary`：生成并写入 KV
|
||
|
||
`POST /api/summary` 请求体示例：
|
||
|
||
```json
|
||
{
|
||
"url": "/post/hello",
|
||
"style": "bullets",
|
||
"text": "这里是文章正文纯文本…"
|
||
}
|
||
```
|
||
|
||
## 接入你的静态文章页
|
||
|
||
你的文章页只需要：
|
||
|
||
1) 正文容器（可换选择器）：
|
||
|
||
```html
|
||
<div class="post">文章内容...</div>
|
||
```
|
||
|
||
2) 放一个摘要组件容器：
|
||
|
||
```html
|
||
<div class="post-summary" data-post-selector=".post" data-style="tldr" data-autoload="false"></div>
|
||
```
|
||
|
||
`data-autoload="false"` 表示不自动请求（避免每次打开页面就触发 `/api/summary`）；用户点击风格按钮时才生成/读取。
|
||
|
||
默认会隐藏下面的摘要内容框（避免占位太大），点击任意风格按钮后才会展开并展示结果。你也可以手动控制初始展开：
|
||
|
||
```html
|
||
<div class="post-summary" data-expanded="true"></div>
|
||
```
|
||
|
||
如果你的站点是深色主题，可以加 `data-theme="dark"`（或强制浅色 `data-theme="light"`）：
|
||
|
||
```html
|
||
<div class="post-summary" data-post-selector=".post" data-style="tldr" data-theme="dark"></div>
|
||
```
|
||
|
||
3) 引入静态资源：
|
||
|
||
```html
|
||
<link rel="stylesheet" href="/summary.css" />
|
||
<script src="/summary.js" type="module"></script>
|
||
```
|
||
|
||
`summary.css` 只会影响 `.post-summary` 组件内部，不会污染你站点的全局样式；demo 页面用到的全局样式在 `public/demo.css`，集成时不要引用它。
|
||
|
||
跨域引入说明：
|
||
|
||
- 如果你的文章站点（如 `https://blog.example.com`）要直接引用另一个域名上的 `summary.js`（并且 `type="module"`），脚本资源必须带 CORS 响应头。
|
||
- 本项目已在 Worker（`src/worker.ts`）和 Pages（`public/_headers`）里为静态资源和 `/api/*` 增加了 `Access-Control-Allow-Origin: *`。
|
||
- 默认情况下，组件会把 API 指向 `summary.js` 所在域名（避免跨域脚本被引入时，错误请求到当前文章站点的 `/api/*`）。
|
||
- 如果前端和 API 不同域名，可在 `.post-summary` 上设置 `data-api-base="https://你的API域名"` 覆盖。
|
||
|
||
排查 KV 没写入：
|
||
|
||
- 打开浏览器 DevTools → Network，确认有 `POST https://你的API域名/api/summary`，并且返回里有 `cached: false`
|
||
- 访问 `https://你的API域名/api/summary?url=/debug&style=tldr`：未缓存时应返回 404（缓存命中才会 200）
|
||
|
||
## 仍想用 Workers（可选）
|
||
|
||
如果你仍想用纯 Workers（不走 Pages）：
|
||
|
||
- `npm run dev:worker`
|
||
- `npm run deploy:worker`
|
||
- KV id 配置参考 `wrangler.toml`
|