openclaw-server 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,319 @@
+# openclaw-server
+
+`openclaw-server` 是一个给 OpenClaw 用的 OpenAI-compatible 后端。
+
+它不是通用大模型，也不会调用真实 AI API。当前版本的重点很明确: 把 [书签篮](https://shuqianlan.com) 的搜索、分类浏览和最近更新能力，包装成 OpenClaw 可以直接接入的聊天服务。
+
+如果你想让 OpenClaw 在聊天里直接回答下面这类问题，这个项目就是最短路径:
+
+- `搜 python`
+- `搜索 cesium 教程`
+- `看看最近更新`
+- `列出分类`
+- `开发工具常用链接`
+- `每天早上 6 点推送最近更新的文章`
+
+## 为什么要接书签篮
+
+[书签篮](https://shuqianlan.com) 适合把常用网站、教程、工具、文章整理成一个长期可维护的知识入口。  
+把它接进 OpenClaw 之后，机器人返回的就不再只是“网上搜一下”的泛结果，而是你已经沉淀好的个人或团队导航内容。
+
+这个项目当前内置的数据源就是 `https://shuqianlan.com`。
+
+## 当前能力
+
+- 关键词搜索书签篮内容
+- 查看最近更新文章
+- 列出一级分类
+- 查看某个分类下的文章
+- 查看某个分类下的常用链接
+- 支持 `GET /healthz`
+- 支持 `GET /v1/models`
+- 支持 `POST /v1/chat/completions`
+- 支持 `POST /v1/responses`
+- 支持 SSE 流式输出
+- 支持每天定时生成“最近更新文章”摘要
+- 能识别 OpenClaw 包装过的用户输入，并提取其中的真实文本和 `sender_id`
+
+## 快速开始
+
+### 1. 环境要求
+
+- Node.js `>= 22.12.0`
+- `pnpm`
+
+### 2. 安装依赖
+
+```bash
+pnpm install
+```
+
+### 3. 配置环境变量
+
+最少只需要一个 API Key:
+
+```bash
+export OPENCLAW_SERVER_API_KEY='replace-me'
+```
+
+常用配置如下:
+
+```bash
+export OPENCLAW_SERVER_HOST='127.0.0.1'
+export OPENCLAW_SERVER_PORT='4318'
+export OPENCLAW_SERVER_API_KEY='replace-me'
+export OPENCLAW_SERVER_MODEL_ID='default-assistant'
+export OPENCLAW_SERVER_DEBUG_LOG='1'
+```
+
+### 4. 启动服务
+
+开发模式:
+
+```bash
+pnpm dev
+```
+
+或直接启动:
+
+```bash
+pnpm start
+```
+
+默认监听:
+
+```text
+http://127.0.0.1:4318
+```
+
+### 5. 健康检查
+
+```bash
+curl http://127.0.0.1:4318/healthz
+```
+
+预期返回:
+
+```json
+{"ok":true,"version":"0.1.0"}
+```
+
+## 直接调用
+
+除了 `/healthz`，其余接口都需要 Bearer Token。
+
+### 查看模型列表
+
+```bash
+curl http://127.0.0.1:4318/v1/models \
+  -H 'Authorization: Bearer replace-me'
+```
+
+### 用 Chat Completions 搜索书签
+
+```bash
+curl http://127.0.0.1:4318/v1/chat/completions \
+  -H 'Authorization: Bearer replace-me' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "default-assistant",
+    "messages": [
+      { "role": "user", "content": "搜 python" }
+    ]
+  }'
+```
+
+### 用 Responses API 搜索书签
+
+```bash
+curl http://127.0.0.1:4318/v1/responses \
+  -H 'Authorization: Bearer replace-me' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "default-assistant",
+    "input": "搜索 notion ai"
+  }'
+```
+
+## 使用方式
+
+服务当前更像一个“书签篮助手”，而不是通用聊天模型。推荐直接对它说明确指令:
+
+- 搜索: `搜 python`、`搜索 cesium 教程`、`帮我找 Notion AI`
+- 最近更新: `看看最近更新`、`最新文章`
+- 分类列表: `列出分类`、`有哪些一级分类`
+- 分类文章: `开发工具分类`、`看看开发工具的文章`
+- 分类链接: `开发工具常用链接`
+- 每日摘要: `每天早上 6 点推送最近更新的文章`
+
+## 接入 OpenClaw
+
+最直接的接法，是把 `openclaw-server` 配成一个自定义 provider。
+
+下面示例里的 `contextWindow` 和 `maxTokens` 主要是给 OpenClaw 填模型目录元数据，按你的使用习惯调整即可。
+
+下面是一份可直接参考的 OpenClaw 配置示例:
+
+```json5
+{
+  env: {
+    OPENCLAW_SERVER_API_KEY: "replace-me",
+  },
+  agents: {
+    defaults: {
+      model: { primary: "openclaw-server/default-assistant" },
+      models: {
+        "openclaw-server/default-assistant": { alias: "书签篮助手" },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "openclaw-server": {
+        baseUrl: "http://127.0.0.1:4318/v1",
+        apiKey: "${OPENCLAW_SERVER_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "default-assistant",
+            name: "Bookmark Assistant",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 32000,
+            maxTokens: 4096,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+接入时注意:
+
+- `baseUrl` 要指向服务的 `/v1`
+- `apiKey` 要和 `OPENCLAW_SERVER_API_KEY` 一致
+- `model` 引用格式是 `providerId/modelId`，这里就是 `openclaw-server/default-assistant`
+- 如果你在 OpenClaw 里统一使用 Responses API，也可以把 `api` 改成 `openai-responses`，本服务同样提供 `/v1/responses`
+
+### 和 OpenClaw 对接时，这个服务会帮你做什么
+
+- 自动从 OpenClaw 包装过的用户消息里提取真实用户输入
+- 自动尝试从 `Conversation info (untrusted metadata)` 里提取 `sender_id`
+- 书签更新订阅会按用户维度保存，便于后续做消息回推或轮询投递
+
+这意味着，OpenClaw 把聊天请求转发过来之后，不需要你再额外清洗一层用户文本。
+
+## 每日更新摘要怎么接
+
+当用户说出类似 `每天早上 6 点推送最近更新的文章` 的指令后，服务会:
+
+1. 记录订阅关系
+2. 定时检查书签篮最近更新
+3. 生成待发送通知
+
+你可以用两种方式把这些通知送出去:
+
+### 方式一: 配置 webhook 自动投递
+
+```bash
+export OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_URL='https://your-bridge.example.com/hooks/bookmark-digest'
+export OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_AUTH_TOKEN='replace-me'
+```
+
+服务会定时向该地址发送 JSON:
+
+```json
+{
+  "type": "bookmark_digest",
+  "user": "sender-1",
+  "message": "早上好，以下是 ...",
+  "payload": {
+    "type": "bookmark_digest",
+    "userId": "sender-1",
+    "slotAt": "2026-03-14T06:00:00.000Z",
+    "hasNewArticles": true,
+    "articles": [],
+    "browseUrl": "https://shuqianlan.com/static-article/page/page_1.html"
+  }
+}
+```
+
+### 方式二: 自己轮询管理接口
+
+拉取待发送通知:
+
+```bash
+curl 'http://127.0.0.1:4318/admin/bookmark-digests/pending?user=sender-1' \
+  -H 'Authorization: Bearer replace-me'
+```
+
+标记已送达:
+
+```bash
+curl http://127.0.0.1:4318/admin/bookmark-digests/mark-delivered \
+  -H 'Authorization: Bearer replace-me' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "ids": ["notification-id"]
+  }'
+```
+
+如果你当前只想先把搜索能力接进 OpenClaw，这一部分可以先不配。
+
+## 管理接口
+
+- `GET /healthz`: 健康检查，无需鉴权
+- `GET /v1/models`: 返回模型列表
+- `POST /v1/chat/completions`: OpenAI Chat Completions 兼容接口
+- `POST /v1/responses`: OpenAI Responses 兼容接口
+- `GET /admin/stats`: 查看运行时统计
+- `POST /admin/packs/reload`: 热重载 `packs/<packId>`
+- `GET /admin/bookmark-digests/pending`: 查看待发送摘要
+- `POST /admin/bookmark-digests/mark-delivered`: 标记摘要已送达
+
+## 常用环境变量
+
+- `OPENCLAW_SERVER_HOST`: 监听地址，默认 `127.0.0.1`
+- `OPENCLAW_SERVER_PORT`: 监听端口，默认 `4318`
+- `OPENCLAW_SERVER_API_KEY`: 鉴权令牌，默认 `openclaw-server-dev`
+- `OPENCLAW_SERVER_MODEL_ID`: 默认模型 ID，默认 `default-assistant`
+- `OPENCLAW_SERVER_PACK_ID`: 要加载的 pack，默认 `default`
+- `OPENCLAW_SERVER_PACK_DIR`: 自定义 pack 目录
+- `OPENCLAW_SERVER_SESSION_LOG`: 会话日志输出路径
+- `OPENCLAW_SERVER_TIMEZONE`: 默认时区
+- `OPENCLAW_SERVER_BOOKMARK_DIGEST_TIMEZONE`: 摘要时区
+- `OPENCLAW_SERVER_BOOKMARK_DIGEST_POLL_MS`: 摘要轮询间隔
+- `OPENCLAW_SERVER_BOOKMARK_DIGEST_LIMIT`: 每次摘要最多带多少条文章
+- `OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_URL`: 自动投递 webhook
+- `OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_AUTH_TOKEN`: webhook Bearer Token
+- `OPENCLAW_SERVER_DEBUG_LOG`: 是否开启调试日志
+
+## 自定义回复
+
+默认 pack 在 `packs/default`，你可以直接修改这些文件来调整回复风格和兜底逻辑:
+
+- `packs/default/pack.yaml`
+- `packs/default/intents.yaml`
+- `packs/default/templates.yaml`
+- `packs/default/faq.yaml`
+- `packs/default/scenarios.yaml`
+
+修改后可以调用:
+
+```bash
+curl http://127.0.0.1:4318/admin/packs/reload \
+  -X POST \
+  -H 'Authorization: Bearer replace-me'
+```
+
+## 当前边界
+
+- 它不是通用大模型服务
+- 它当前不调用真实 AI API
+- 它当前的核心价值是“把书签篮接到 OpenClaw 里”
+- 它当前内置的数据源是 [书签篮](https://shuqianlan.com)
+
+如果你的目标是让 OpenClaw 拥有一个真正可搜索、可沉淀、可长期维护的资料入口，而不是再接一个泛化聊天模型，这个项目和书签篮的组合会很合适。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Independent faux AI backend for OpenClaw",
   "type": "module",

package/packs/default/templates.yaml

@@ -1,16 +1,16 @@
-- id: greeting.default
+- id: greeting.default
   variants:
-    - "你好，我是 openclaw-server。我可以帮你创建任务、设置提醒、查询待办，也支持按城市查询今天、明天、后天的天气。"
-    - "我在。当前这个服务不会调用真实 AI API，但可以用规则、模板和场景帮你处理固定而实用的业务需求。"
+    - "你好，我是 openclaw-server。现在我只提供书签栏里的书签搜索，你可以直接说“搜 python”“搜索 cesium 教程”或“帮我找 Notion AI”。"
+    - "我在。当前这个服务不会调用真实 AI API，只保留了书签栏搜索能力。直接给我关键词，我就返回可点击的书签结果。"
 
 - id: capabilities.help
   variants:
-    - "我目前支持两类业务功能：一类是任务和提醒，比如创建待办、补充提醒、查询今天/明天/本周任务，以及完成、延后、取消提醒任务；另一类是天气查询，比如按城市查询今天、明天、后天的天气。如果缺地点或时间，我会继续追问。"
+    - "我目前只支持书签栏里的书签搜索。你可以直接说“搜 python”“搜索 cesium”“帮我找教程”“查找 Notion AI”，我会返回可点击的标题链接。"
 
 - id: faq.real-ai
   variants:
-    - "不是。我不会调用真实 AI API。当前回复来自 `openclaw-server` 的知识包、规则匹配、模板和多轮场景编排。"
+    - "不是。我不会调用真实 AI API。当前回复来自 `openclaw-server` 的固定规则和书签栏搜索结果。"
 
 - id: fallback.default
   variants:
-    - "这个我暂时没准确听懂。你可以直接说具体需求，比如“明天下午 3 点提醒我开会”、“我有哪些任务”或“天津明天天气如何”，我会按这个方向继续帮你。"
+    - "我现在只保留了书签栏搜索。你可以直接说“搜 python”“搜索 cesium 教程”或“帮我找 Notion AI”，我会把对应书签结果发给你。"

package/src/bookmark-digest/chat-integration.ts

@@ -0,0 +1,49 @@
+import type { EngineResult, NormalizedTurn } from "../types.js";
+import type { BookmarkDigestChatResult, BookmarkDigestMessageInspection } from "./types.js";
+import type { BookmarkDigestService } from "./service.js";
+
+export function inspectBookmarkDigestMessage(params: {
+  bookmarkDigestService: BookmarkDigestService;
+  turn: NormalizedTurn;
+}): BookmarkDigestMessageInspection {
+  return params.bookmarkDigestService.inspectMessage({
+    text: params.turn.userText,
+  });
+}
+
+export function buildBookmarkDigestEngineResult(params: {
+  turn: NormalizedTurn;
+  digestResult: BookmarkDigestChatResult;
+}): EngineResult {
+  return {
+    model: params.turn.model,
+    sessionId: params.turn.sessionId,
+    text: params.digestResult.reply,
+    finishReason: "stop",
+    matchedIntentId: `bookmark-digest.${params.digestResult.intent}`,
+    templateId: `bookmark-digest.${params.digestResult.intent}`,
+  };
+}
+
+export function respondToBookmarkDigestMessage(params: {
+  bookmarkDigestService: BookmarkDigestService;
+  turn: NormalizedTurn;
+  userId: string;
+  now?: string;
+}): EngineResult | undefined {
+  const inspection = inspectBookmarkDigestMessage(params);
+  if (!inspection.shouldHandle) {
+    return undefined;
+  }
+
+  const digestResult = params.bookmarkDigestService.processMessage({
+    userId: params.userId,
+    text: params.turn.userText,
+    now: params.now,
+  });
+
+  return buildBookmarkDigestEngineResult({
+    turn: params.turn,
+    digestResult,
+  });
+}

package/src/bookmark-digest/service.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { BookmarkSearchProvider } from "../bookmark-search/types.js";
+import { BookmarkDigestService } from "./service.js";
+import { BookmarkDigestStore } from "./store.js";
+
+function createProvider(): BookmarkSearchProvider {
+  return {
+    searchKeyword: vi.fn(async () => []),
+    listLatestArticles: vi.fn(async () => ({
+      items: [
+        {
+          type: "文章",
+          title: "Cesium 获取地形高度 全面深度教程",
+          desc: "覆盖地形高度采样、坐标转换和实际项目中的精度处理。",
+          firstCategory: "开发工具",
+          secondCategory: "地图",
+          updatedAt: "2026-03-13 18:20:00",
+          url: "https://shuqianlan.com/static-article/detail-html/article_cesium_height.html",
+        },
+      ],
+      total: 1,
+      browseUrl: "https://shuqianlan.com/static-article/page/page_1.html",
+    })),
+  };
+}
+
+describe("BookmarkDigestService", () => {
+  const stores: BookmarkDigestStore[] = [];
+
+  afterEach(() => {
+    for (const store of stores.splice(0)) {
+      store.close();
+    }
+  });
+
+  it("subscribes users and schedules only one digest per day", async () => {
+    const store = new BookmarkDigestStore(":memory:");
+    stores.push(store);
+    const service = new BookmarkDigestService(store, createProvider(), {
+      pollMs: 0,
+      timeZone: "Asia/Shanghai",
+    });
+
+    const subscribed = service.processMessage({
+      userId: "u1",
+      text: "每天早晨6点将最近更新的文章推送给我",
+      now: "2026-03-13T05:30:00+08:00",
+    });
+    expect(subscribed.intent).toBe("subscribed");
+    expect(subscribed.reply).toContain("06:00");
+
+    expect(await service.dispatchDueDigests("2026-03-13T05:59:00+08:00")).toBe(0);
+    expect(await service.dispatchDueDigests("2026-03-13T06:00:00+08:00")).toBe(1);
+    expect(await service.dispatchDueDigests("2026-03-13T06:05:00+08:00")).toBe(0);
+
+    const pending = service.listPendingNotifications({ userId: "u1" });
+    expect(pending).toHaveLength(1);
+    expect(pending[0]?.message).toContain("最近更新文章");
+    expect(pending[0]?.message).toContain("article_cesium_height.html");
+  });
+
+  it("retries pending notifications through the configured webhook and marks them delivered", async () => {
+    const store = new BookmarkDigestStore(":memory:");
+    stores.push(store);
+    const fetchImpl = vi.fn(async () => new Response(null, { status: 204 }));
+    const service = new BookmarkDigestService(store, createProvider(), {
+      pollMs: 0,
+      timeZone: "Asia/Shanghai",
+      webhookUrl: "https://example.com/hooks/bookmark-digest",
+      webhookAuthToken: "secret-token",
+      fetchImpl,
+    });
+
+    service.processMessage({
+      userId: "u1",
+      text: "每天早上6点推送最近更新的文章",
+      now: "2026-03-13T05:30:00+08:00",
+    });
+    await service.dispatchDueDigests("2026-03-13T06:00:00+08:00");
+
+    expect(await service.deliverPendingNotifications("2026-03-13T06:00:10+08:00")).toBe(1);
+    expect(fetchImpl).toHaveBeenCalledTimes(1);
+    expect(fetchImpl.mock.calls[0]?.[1]).toMatchObject({
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer secret-token",
+      },
+    });
+    expect(service.listPendingNotifications({ userId: "u1" })).toHaveLength(0);
+  });
+});