给 Hexo 博客加了联机小游戏（德州扑克）后，遇到了最头疼的一环：WebRTC 建立连接前必须先经过信令服务器交换 SDP 与 ICE 候选。官方 PeerJS Cloud Server 是实验性的、延迟高、还不稳定，于是决定自己部署一个，正好博客本身跑在 Cloudflare 上，直接用一个 Worker 搞定。

下面的代码与步骤都经过双客户端实测通过（两个浏览器窗口正常互通握手）。

为什么需要信令服务器

WebRTC 的数据通道（DataChannel）虽然是点对点的，但建立对等连接的过程需要第三方帮忙：

1. 双方首先要交换各自的连接信息（SDP + ICE Candidate）
2. 这个”撮合”过程必须走一个双方都能访问的中转服务器
3. WebRTC 本身不提供这个中转，PeerJS 引用了它

PeerJS 的工作流程大致是：

1
2
3

[A] --WS--> 信令服务器 --WS--> [B]
   <--OFFER/ANSWER/ICE--转发-->
连接建立后：A 与 B 改为 P2P 直连，信令服务器退出数据路径

所以信令服务器只负责”介绍”，游戏数据本身不经过它，这也是它可以用非常轻量的 Worker 来实现的原因。

为什么选 Cloudflare Workers + Durable Objects

PeerJS 的信令需要有状态的 WebSocket 长连接（要记住每个玩家 id 对应哪个连接，以便转发）。普通 Worker 是无状态的，无法跨请求保存 WebSocket 状态。而 Durable Object（DO） 正是为这种有状态 WebSocket 场景设计的：

完整 Worker 代码

新建 worker.js，粘贴下面代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

import { DurableObject } from 'cloudflare:workers';

// ── 入口 ────────────────────────────────────────────────
export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // 健康检查 / 根路径提示
    if (url.pathname === '/' || url.pathname === '') {
      return new Response('PeerJS Server is running on Cloudflare Workers!', {
        headers: { 'content-type': 'text/plain' },
      });
    }

    // 解析信令路径：/peerjs/id/<peerId>?key=peerjs
    const peerId = url.pathname.split('/peerjs/id/')[1] || url.pathname.split('/id/')[1];
    if (!peerId) {
      return new Response('Not found', { status: 404 });
    }
    // URL 中的 id 参数优先，其次取路径中的 peerId（PeerJS 会带 ?id=<id>&key=peerjs）
    const finalId = url.searchParams.get('id') || peerId;

    // 用 peerId 生成一个稳定 socket，保证同一个 id 落到同一个 DO 实例
    const id = env.PEER_SERVER.idFromName(finalId);
    const stub = env.PEER_SERVER.get(id);
    return stub.fetch(request);
  },
};

// ── Durable Object：真正处理 WebSocket ──────────────────
export class PeerServer extends DurableObject {
  constructor(ctx, env) {
    super(ctx, env);
    this.ws = null;         // 本实例持有的玩家 WebSocket
    this.peerId = null;     // 当前连接的玩家 id
  }

  async fetch(request) {
    const url = new URL(request.url);
    this.peerId = url.searchParams.get('id') || '';

    // PeerJS 会发送 WebSocket 升级请求
    const upgradeHeader = request.headers.get('Upgrade') || '';
    if (upgradeHeader.toLowerCase().includes('websocket')) {
      const [client, server] = Object.values(new WebSocketPair());
      server.acceptWith(this);

      // 已有一个 id 持有连接 → 提示冲突，拒绝第二个
      if (this.ws) {
        server.send(JSON.stringify({
          type: 'ALERT',
          payload: { type: 'unavailable' },
          src: 'server',
          dst: this.peerId,
        }));
      }
      this.ws = server;

      // 回发 OPEN 确认（PeerJS 注册成功的关键）
      server.send(JSON.stringify({
        type: 'OPEN',
        src: 'server',
        id: this.peerId,
      }));

      return new Response(null, { status: 101, webSocket: client });
    }
    return new Response('Expected WebSocket', { status: 400 });
  }

  // 收到的消息
  async websocketMessage(ws, message) {
    let msg;
    try { msg = JSON.parse(message); } catch { return; }

    // DELETE/LEAVE 类型 → 掉线清理
    if (msg.type === 'DELETE' || msg.eventType === 'leave' || msg.type === 'CLOSE') {
      try { ws.close(1000, 'bye'); } catch (e) {}
      // 通知同伴该玩家已离开
      if (this.ws && this.ws !== ws) {
        try {
          this.ws.send(JSON.stringify({
            type: 'unavailable',
            src: 'server',
            dst: msg.src,
          }));
        } catch (e) {}
      }
      this.ws = ws === this.ws ? null : this.ws;
      return;
    }

    // 是发给对端玩家的信令（OFFER/ANSWER/ICE 等），通过另一个握手接线的对方转发
    // 这里只是单房间实现，多玩家房间需要维护 this.clients 映射按 dst 转发
    if (this.ws && this.ws !== ws) {
      try {
        this.ws.send(JSON.stringify(msg));
      } catch (e) {}
    }
  }

  async websocketClose() {
    this.ws = null;
  }
}

说明：上面是一个一房一级（房间 = ID）的最小实现，适合「一人建房一人入房」的双人对局（每个玩家 id 对应一个独立 DO 实例，互不干扰）。如果你的游戏是多人房间，需要改为所有玩家进入同一个 DO（用同一个 name）并在内部维护 Map<peerId, ws> 按目标转发，同时把 dst 回写为对端 peerId 防止篡改。

踩坑记录（重要）

部署过程中最容易在这里卡住，逐个说明：

坑 1：新版 Durable Object 语法（最关键）

Cloudflare 在 2024 年起已废弃旧的 class extends DurableObject 隐式导出，新语法必须：

1
2
3
4
5

import { DurableObject } from 'cloudflare:workers';

export class PeerServer extends DurableObject {
  ...
}

原因：控制台「添加绑定」界面会扫描 Worker 代码里的 extends DurableObject 来列出可选类名。如果你用的是旧式写法，绑定界面会显示「未找到 Durable Object / 0 个选项」，导致无法添加绑定。

坑 2：ESM 代码 Content-Type 必须是 application/javascript+module

如果你通过 Cloudflare API（/accounts/{id}/workers/services/{name}）上传代码，脚本文件必须带上：

1

Content-Type: application/javascript+module

否则会报 Unexpected token 'export'——因为服务端把 ESM 当作了经典脚本。很多人首传都栽在这。

坑 3：绑定配置（metadata）要与非绑定一起提交

用 API 部署时，绑定属于 metadata 的一部分。要用 HTTP 上传（新版本 API）同时提交 metadata（内含有 main_module 与 bindings）。如果不带 bindings，页面看着部署了，实际 WebSocket 会返回 500（代码 1101），因为 Worker 里 env.PEER_SERVER 是 undefined。

部署步骤

方式 A：Dashboard 手动（适合首次尝试）

1. 进入 Cloudflare Dashboard → Workers & Pages → 创建 Worker
2. 粘贴上面的 worker.js 代码 → 保存并部署
3. 进入 Worker 的 设置 → 绑定 → 添加绑定
4. 绑定类型选择 Durable Object（注意别选成 KV）
5. 变量名填 PEER_SERVER，绑定类名选代码里的 PeerServer
6. 部署完成后，浏览器访问 https://你的-worker-子域.workers.dev 应返回 PeerJS Server is running on Cloudflare Workers!

方式 B：Wrangler CLI（推荐用于项目化管理）

1
2

npm init -y
npm install -D wrangler

创建 wrangler.toml：

1
2
3
4
5
6
7
8
9
10
11

name = "peerjs-server"
main = "worker.js"
compatibility_date = "2024-01-01"

[[durable_objects.bindings]]
name = "PEER_SERVER"
class_name = "PeerServer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["PeerServer"]

登录并部署：

1
2

npx wrangler login
npx wrangler deploy

DO 迁移是一次性操作，第二次部署若重复声明 new_sqlite_classes 会报 Migration conflict。新增类改成：

1
2
3

[[migrations]]
tag = "v2"
new_classes = ["AnotherClass"]

前端接入（Hexo 页面）

在一个 HTML 游戏页面引入 peerjs，并连接到你的 Worker：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<script src="https://unpkg.com/peerjs@1.5.4/dist/peerjs.min.js"></script>
<script>
  var myId = 'my-room-id'; // 房间名 / 玩家 id

  var peer = new Peer(myId, {
    host: '你的-worker子域.workers.dev',
    port: 443,        // 部署在 HTTPS，443
    secure: true,
    debug: 1,         // 1 输出关键日志，便于排查
    // 默认 path 就是 /peerjs，无需改
  });

  peer.on('open', function (id) {
    console.log('已注册，id =', id);
  });

  peer.on('connection', function (conn) {
    console.log('对方接入', conn);
    conn.on('data', function (data) {
      // 处理对方发来的信令数据
    });
    conn.on('open', function () { conn.send('hello'); });
  });

  peer.on('error', function (err) {
    console.error('PeerJS 错误 :', err.type, '-', err.message);
  });
</script>

关键点：

• host 必须指向你的 Worker 子域（xxx.workers.dev）
• secure: true（你的 Worker 域名是 HTTPS）
• 连接若总是报 peer-unavailable，检查 DO 绑定是否真的存在（最常见坑 3）

安全提示

• 不要泄露敏感信息：wrangler.toml 中的绑定 ID、Dashboard 里的账号 ID 属于你的私有资源，不要在博客/代码里公开。
• 这个实现没有做鉴权（任意 id 都能注册），只适合个人博客的娱乐联机，有心者可以伪造身份——要防外挂请在设计层面解决：联机扑克重要的防作弊手段是对手的手牌永不发送到你的浏览器，只发送公共牌与结算结果，这是由游戏逻辑保证的，而不是信令服务器。

测试验证

部署后可同样在浏览器开两个窗口各跑上面那段连接代码，用两个不同的房间 id，观察：

• 两个窗口都打印 已连接
• A 发送 OFFER，B 能收到并回发 ANSWER
• 消息能到达两端（P2P 建立）

我这边实测两窗口互通正常。

总结

• Cloudflare Workers + DO 完全可以托管 PeerJS 信令服务器，免费、低延迟
• 核心 3 坑：新版 DO 语法、ESM Content-Type、绑定 metadata
• 信令中转很「透明」，真正的防作弊/逻辑在应用层

RSS（Really Simple Syndication）是一种网页内容聚合格式，让你可以通过 RSS 阅读器 一站式订阅多个博客、新闻站点，不用一个个网站去刷。

当博客发布新文章时，阅读器会自动拉取更新。

本博客支持的 Feed 地址

两种格式任选其一，功能完全一样：

Atom vs RSS 2.0 有什么区别？

简单说：对你没区别，选哪个都行。如果你不确定，用 Atom。

推荐的 RSS 阅读器

在线服务

• Feedly — 最流行的在线 RSS 阅读器，支持多平台
• Inoreader — 功能强大，支持规则过滤和搜索

桌面端

• NetNewsWire（macOS）— 免费开源
• Fluent Reader（Windows / macOS / Linux）— 免费开源
• irreader（Windows）— 国产，支持订阅和阅读

移动端

• Feedly（iOS / Android）
• Inoreader（iOS / Android）
• NetNewsWire（iOS）

如何订阅

以 Feedly 为例：

1. 打开 Feedly
2. 点击右上角 “Follow”
3. 输入 https://neoisconstantine-github-io.pages.dev/atom.xml
4. 点击 “Follow” 即可

其他阅读器操作类似，一般都有”添加订阅”或”Add Feed”的入口，粘贴 Feed 地址就行。

• Node.js >= 20
• Chrome 浏览器
• 已安装 chrome-devtools-mcp（首次运行自动安装）

第一步：Chrome 开启远程调试

1. 正常打开 Chrome（不需要任何命令行参数）
2. 地址栏输入：

   1	chrome://inspect#remote-debugging

3. 勾选 “Enable remote debugging”
4. 页面显示 Server running at: starting… 即表示就绪

⚠️ 每次重启 Chrome 后都需要重新开启此设置

第二步：获取 WebSocket 地址

Chrome 会在用户数据目录生成 DevToolsActivePort 文件，里面包含调试端口和 WebSocket 路径：

1
2
3
4
5
6
7
8

文件位置：
%LOCALAPPDATA%\Google\Chrome\User Data\DevToolsActivePort

内容示例：
9222
/devtools/browser/1e19be11-dcf8-4255-9133-f63c7a971911

WebSocket 地址 = ws://127.0.0.1:9222/devtools/browser/1e19be11-xxx

第三步：启动 MCP 服务器连接

方式一：通过 WebSocket 直连（推荐）

1

npx --yes chrome-devtools-mcp@latest --wsEndpoint=ws://127.0.0.1:9222/devtools/browser/xxx

方式二：自动连接（需要 Chrome 已开启远程调试）

1

npx --yes chrome-devtools-mcp@latest --autoConnect

注意事项

⚠️ 不要做的事

✅ 正确做法

• Chrome 正常启动，不加任何额外参数
• 只需在 chrome://inspect#remote-debugging 开启调试
• MCP 连接用 --wsEndpoint 参数，从 DevToolsActivePort 文件获取地址

端口说明

Chrome 的 inspect 远程调试端口特点：

• 端口号写在于 DevToolsActivePort 文件中
• 只接受 WebSocket 连接，不接受 HTTP 请求
• 访问 http://127.0.0.1:9222/json/version 会返回 404

可用 MCP 工具

连接成功后可通过 MCP 协议使用以下工具：

导航

• navigate_page — 跳转到 URL
• list_pages — 列出所有标签页
• select_page — 切换标签页
• new_page — 打开新标签页
• close_page — 关闭标签页

操作

• click — 点击元素
• fill — 填写输入框
• fill_form — 填写整个表单
• type_text — 输入文本
• press_key — 按键
• hover — 悬停

调试

• take_screenshot — 截图
• take_snapshot — 获取页面无障碍树
• evaluate_script — 执行 JavaScript
• get_console_message — 获取控制台日志
• list_console_messages — 列出控制台消息

网络

• list_network_requests — 列出网络请求
• get_network_request — 获取网络请求详情

性能

• performance_start_trace — 开始性能录制
• performance_stop_trace — 停止性能录制
• performance_analyze_insight — 分析性能洞察

OpenCode 配置

在项目根目录创建 opencode.json：

1
2
3
4
5
6
7
8
9

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

注意：配置后需要重启 OpenCode 才能生效

故障排查

MCP 初始化成功但工具调用失败

1

Error: Failed to fetch browser webSocket URL from http://.../json/version: HTTP Not Found

→ 改用 --wsEndpoint 代替 --browser-url

DevToolsActivePort 文件不存在

→ 打开 chrome://inspect#remote-debugging 开启远程调试

Chrome 提示”正受到自动测试软件控制”

→ 这是正常的，表示 MCP 已连接成功

连接断开

→ 重新打开 chrome://inspect#remote-debugging 获取新的 WebSocket 地址重连

业界主流方案、优势、实现方式与代码示例
更新日期：2026-06-17

背景问题

AI 对话中，每次请求都会把完整的历史消息（包括 thinking、工具调用输出、文件内容等）传给模型。随着对话拉长，上下文迅速膨胀，带来三个问题：

• 成本高：按 token 计费，上下文越长越贵
• 速度慢：首 token 延迟随上下文长度线性增加
• 质量下降：”Lost in the Middle” 现象——模型对上下文中间部分关注力最差

1

Token 消耗 ≈ 系统提示 + 历史对话 × 轮数 + 工具输出 × 调用次数

即使模型支持 200K/1M token 窗口，装得下 ≠ 效果好 + 花钱少。

方案一：删除压缩（Compaction）

原理

直接删除低信号内容，保留的原文一字不改。不生成新 token，零幻觉风险。

典型删除对象：

• 工具调用的原始输出（grep 返回的 100 个文件 → 只保留匹配行）
• 文件 diff 的全量内容 → 只保留变更摘要
• 浏览器截屏的冗长 HTML → 只保留关键文本
• 重复的 thinking 过程

优势

业界工具

• Headroom — 开源上下文压缩层，10k+ star。SmartCrusher(JSON) + CodeCompressor(AST) + Kompress-base(文本)，压缩率 90%+
• RTK — 压缩 CLI 命令输出（git show、ls 等）
• lean-ctx — CLI + MCP 工具的上下文精简

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 简单的 compaction：只保留 grep 结果中的文件名和匹配行
function compactGrepOutput(raw: string): string {
  const lines = raw.split('\n');
  const significant = lines.filter(line => {
    // 过滤掉：空行、只有行号的行、重复的分隔线
    return line.trim() && !/^─+$/.test(line) && !/^\d+$/.test(line);
  });
  return significant.join('\n');
}

// 更智能的：JSON 响应只保留关键字段
function compactJsonResponse(raw: string, keepFields: string[]): string {
  const parsed = JSON.parse(raw);
  if (Array.isArray(parsed)) {
    return JSON.stringify(parsed.map(item => {
      const result: Record<string, any> = {};
      for (const field of keepFields) {
        if (field in item) result[field] = item[field];
      }
      return result;
    }));
  }
  return raw;
}

方案二：摘要压缩（Summarization）

原理

用 LLM 将多轮对话/长文本提炼成一段摘要，替换原始内容。后续对话基于摘要 + 最近的 N 轮完整消息进行。

优势

劣势

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

class ConversationSummarizer {
  private summary = '';
  private recentMessages: Message[] = [];
  private readonly threshold = 4000; // token 阈值

  addMessage(msg: Message) {
    this.recentMessages.push(msg);
    if (this.estimateTokens() > this.threshold) {
      this.compress();
    }
  }

  async compress() {
    const toCompress = this.summary
      + '\n' + this.recentMessages.map(m => `${m.role}: ${m.content}`).join('\n');

    const prompt = `请将以下对话历史压缩成一段简洁摘要，保留：
1. 用户的关键信息（身份、偏好、已做的决定）
2. 重要的任务状态和上下文
3. 后续对话可能需要的事实

原始对话：
${toCompress}

摘要：`;

    this.summary = await llm.chat(prompt);
    this.recentMessages = []; // 压缩后清空
    // 或保留最后 1-2 轮防止断层
  }

  buildContext(): string {
    if (!this.summary) return this.recentMessages.map(m => `${m.role}: ${m.content}`).join('\n');
    return `【历史摘要】\n${this.summary}\n\n【最近对话】\n${
      this.recentMessages.map(m => `${m.role}: ${m.content}`).join('\n')
    }`;
  }

  private estimateTokens(): number {
    const totalChars = this.summary.length
      + this.recentMessages.map(m => m.content.length).reduce((a, b) => a + b, 0);
    return Math.ceil(totalChars / 2); // 中文字符估算
  }
}

业界使用案例

方案三：滑动窗口（Sliding Window）

原理

只保留最近 N 轮对话，更早的全部丢弃。实现最简单。

常见策略

优势

劣势

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

// 按 token 数滑动窗口
function slidingWindow(messages: Message[], maxTokens: number): Message[] {
  let total = 0;
  const result: Message[] = [];

  // 从最新的消息开始往前数
  for (let i = messages.length - 1; i >= 0; i--) {
    const tokens = estimateTokens(messages[i].content);
    if (total + tokens > maxTokens) break;
    total += tokens;
    result.unshift(messages[i]); // 保持顺序
  }

  // 始终保留系统提示（第一条）
  if (messages[0]?.role === 'system') {
    if (result[0]?.role !== 'system') {
      result.unshift(messages[0]);
    }
  }

  return result;
}

// 更精细的：保留首尾，截断中间（Lost in the Middle 优化）
function smartWindow(messages: Message[], maxTokens: number): Message[] {
  if (estimateTotalTokens(messages) <= maxTokens) return messages;

  const systemMsg = messages.filter(m => m.role === 'system');
  const history = messages.filter(m => m.role !== 'system');

  // 保留最近 30% 的 token 预算给尾部
  const tailBudget = Math.floor(maxTokens * 0.3);
  const headBudget = maxTokens - tailBudget - estimateTotalTokens(systemMsg);

  const tail: Message[] = [];
  let tailTokens = 0;
  for (let i = history.length - 1; i >= 0; i--) {
    const t = estimateTokens(history[i].content);
    if (tailTokens + t > tailBudget) break;
    tailTokens += t;
    tail.unshift(history[i]);
  }

  // 从头部取到 headBudget
  const head: Message[] = [];
  let headTokens = 0;
  for (const msg of history) {
    if (head.includes(msg) || tail.includes(msg)) break; // 不重复
    const t = estimateTokens(msg.content);
    if (headTokens + t > headBudget) break;
    headTokens += t;
    head.push(msg);
  }

  return [...systemMsg, ...head, ...tail];
}

方案四：向量记忆 / RAG（检索式记忆）

原理

不保存全部历史，而是把消息向量化存入数据库（Chroma、Milvus 等），每次只检索最相关的几条。

优势

劣势

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

class VectorMemory {
  constructor(
    private embeddingClient: EmbeddingAPI,
    private vectorDb: VectorDatabase,
    private topK = 5
  ) {}

  async addMessage(msg: Message) {
    const embedding = await this.embeddingClient.embed(msg.content);
    await this.vectorDb.insert({
      id: msg.id,
      vector: embedding,
      metadata: {
        role: msg.role,
        timestamp: msg.timestamp,
        content: msg.content
      }
    });
  }

  async retrieve(query: string, limit = 5): Promise<Message[]> {
    const queryEmbedding = await this.embeddingClient.embed(query);
    const results = await this.vectorDb.search(queryEmbedding, limit);
    return results.map(r => ({
      role: r.metadata.role,
      content: r.metadata.content,
      timestamp: r.metadata.timestamp
    }));
  }

  // 构建上下文：系统提示 + 检索结果 + 最近 N 轮
  async buildContext(query: string, recentMessages: Message[]): Promise<string> {
    const relevant = await this.retrieve(query, this.topK);
    const context = [
      '【相关历史】',
      ...relevant.map(m => `${m.role}: ${m.content}`),
      '',
      '【最近对话】',
      ...recentMessages.map(m => `${m.role}: ${m.content}`)
    ].join('\n');
    return context;
  }
}

方案五：多代理隔离（Multi-Agent Isolation）

原理

每个子代理维护自己的小上下文，只关注自己的任务。主代理只持有摘要级别的全局上下文。

优势

劣势

实现示意

1
2
3
4
5
6
7
8
9
10
11

                 ┌─────────────────┐
                 │   Orchestrator   │  ← 只持有摘要上下文
                 │   (主代理)       │
                 └────────┬────────┘
                         │
       ┌─────────────────┼─────────────────┐
       ▼                 ▼                  ▼
┌────────────┐   ┌────────────┐   ┌────────────┐
│   Frontend  │   │    Backend  │   │  Database  │  ← 每个只关心自己的上下文
│   Agent     │   │    Agent    │   │   Agent    │
└────────────┘   └────────────┘   └────────────┘

方案六：上下文缓存（Context Caching）

原理

静态上下文（系统提示、文档、知识库）只在第一次完整传入，后续请求复用缓存结果，只传变化的部分。

提供商支持

适用场景

• 固定文档的大量提问（产品说明书、法律文档、代码库分析）
• 高流量的 AI 应用（同一份知识库被反复查询）
• Agent 长期任务（系统提示不变，只变用户输入）

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Pseudocode：上下文缓存 + 增量更新
class ContextCache {
  private cache: Map<string, CachedContext> = new Map();

  async getOrCreate(key: string, buildContext: () => Promise<string>): Promise<string> {
    const cached = this.cache.get(key);
    if (cached && !this.isExpired(cached)) {
      return cached.context;
    }

    const context = await buildContext();
    this.cache.set(key, {
      context,
      createdAt: Date.now(),
      ttl: 10 * 60 * 1000 // 10 分钟
    });
    return context;
  }

  private isExpired(cached: CachedContext): boolean {
    return Date.now() - cached.createdAt > cached.ttl;
  }
}

方案七：Token 预算管理（Token Budgeting）

原理

把上下文窗口当成预算来分配，不同部分有不同的优先级。

常见分配

1
2
3
4
5
6
7

总窗口 100K tokens
├── 系统提示:          2K  (2%)    ← 固定
├── 对话历史:         10K  (10%)   ← 滑动窗口 + 摘要
├── 工具输出:         30K  (30%)   ← compaction 压缩
├── 检索文档:         30K  (30%)   ← 按相关性排序
├── 当前用户输入:      3K  (3%)    ← 完整保留
└── 模型回答预留:     25K  (25%)   ← 回复空间

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class TokenBudget {
  private readonly budget = {
    system: 0.02,     // 2%
    history: 0.10,    // 10%
    tools: 0.30,      // 30%
    retrieval: 0.30,  // 30%
    input: 0.03,      // 3%
    output: 0.25      // 25%
  };

  constructor(private maxTokens: number) {}

  allocate(): Record<string, number> {
    return Object.fromEntries(
      Object.entries(this.budget).map(([key, ratio]) => [
        key, Math.floor(this.maxTokens * ratio)
      ])
    );
  }

  enforce(section: string, content: string): string {
    const limit = this.allocate()[section];
    const tokens = estimateTokens(content);
    if (tokens <= limit) return content;

    // 超预算时截断到预算的 90%，留余量
    const target = Math.floor(limit * 0.9);
    return truncateToTokens(content, target);
  }
}

方案八：Thinking 过滤（Thinking Stripping）

原理

在把上下文传给模型之前，剥离 assistant 回复中的 thinking/推理部分，只保留最终回答。

优势

实现示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// 过滤 thinking 内容（如 内容块）
function stripThinking(messages: Message[]): Message[] {
  return messages.map(msg => {
    if (msg.role !== 'assistant') return msg;

    // 移除 块
    const cleaned = msg.content.replace(/[\s\S]*?<\/thinking>/g, '');
    return { ...msg, content: cleaned.trim() };
  });
}

// 过滤工具调用过程中的中间输出
function stripToolOutput(messages: Message[]): Message[] {
  return messages.filter(msg => {
    // 保留最终的 tool result，但过滤中间的阶段性输出
    if (msg.role === 'tool') {
      return msg.isFinalResult ?? true; // 只保留标记为最终结果的
    }
    return true;
  });
}

方案对比总结

组合方案示例

实际生产环境不会只用一种方案，而是多层组合：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

接收用户输入
    │
    ▼
① Token 预算分配          ← 系统提示 2% + 回答预留 25%
    │
    ▼
② Thinking 过滤           ← 剥离上一轮 assistant 的 
    │
    ▼
③ 删除压缩 (Compaction)   ← 压缩工具输出、JSON 响应、日志
    │
    ▼
④ 滑动窗口 + 摘要          ← 最近 20 轮完整 + 更早的历史摘要
    │
    ▼
⑤ 向量检索 (RAG)          ← 根据当前问题，检索最相关的历史
    │
    ▼
   组合成最终上下文 → 传给 LLM

真实案例：OpenCode 当前可以做的是

1
2
3
4
5
6
7
8
9
10

当前状态（你正在用的）：
  ✅ 系统提示 + Behavior Instructions（大几千 token）
  ❌ Thinking 不过滤（我的  全部进上下文）
  ❌ 工具输出不做压缩
  ❌ 对话不做摘要

可以立即做的优化：
  1. 自定义 agent + prompt 规范输出格式
  2. 创建 output-format skill 控制回答结构
  3. 等待 OpenCode 支持 thinking 剥离（目前不支持）

参考资料

• Headroom - 开源上下文压缩工具
• LangChain Context Engineering for Agents
• Anthropic Compaction API
• SurePrompts Context Window Management (2026)
• Kimi 上下文缓存技术
• LLM Context Window Management Guide

在文章的 front-matter 中通过 categories 字段设置，支持层级结构：

1
2
3
4
5
6
7

---
title: 文章标题
categories:
  - 技术
  - 前端
  - React
---

这会呈现为 技术 > 前端 > React 三级分类。也可以只用一级：

1
2
3
4
5

---
title: 文章标题
categories:
  - Cloudflare
---

新建文章时也可以通过路径自动归类：

1

hexo new post "学习 Rust" --path rust/learning-rust

Hexo 会自动从 rust/ 路径推断分类为 rust。

标签（Tags）

标签和分类类似，但没有层级关系，纯粹是平铺的关键词：

1
2
3
4
5
6
7

---
title: 文章标题
tags:
  - Cloudflare
  - Workers
  - Hexo
---

也可以写在一行：

1
2
3
4

---
title: 文章标题
tags: [Cloudflare, Workers, Hexo]
---

分类 vs 标签

修改 scaffold 模板

如果不希望每次新建文章都手动写 categories，可以修改 scaffolds/post.md：

1
2
3
4
5
6

---
title: {{ title }}
date: {{ date }}
categories:
tags:
---

这样 hexo new post 生成的文章就会自动带有 categories: 字段。

兼容 Hexo Fluid 主题 OpenKounter 统计插件的自建后端。

API

响应格式

1

{ "code": 0, "data": { ... } }

部署

前置条件

• Node.js >= 18
• Cloudflare 账号
• 已安装 Wrangler CLI (通过下方命令安装)

1. 安装依赖

1
2

cd workers/openkounter
npm install

2. 登录 Cloudflare

1

npx wrangler login

3. 创建 KV 命名空间

⚠️ Wrangler v4+ 使用空格分隔子命令（旧版 kv:namespace 冒号语法已废弃）。

1
2
3
4
5

# 方式 A：使用 npm script（推荐）
npm run kv:create

# 方式 B：直接使用 npx
npx wrangler kv namespace create COUNTERS

输出类似：

1
2
3
4
5
6

📦 Creating namespace with title "openkounter-COUNTERS"
✨ Success!
Add the following to your wrangler.toml:
[[kv_namespaces]]
binding = "COUNTERS"
id = "abc123def..."

将输出的 id 填入 wrangler.toml：

1
2
3
4

[[kv_namespaces]]
binding = "COUNTERS"
id = "abc123def..."           # ← 替换为实际 ID
preview_id = "abc123def..."   # ← 替换为实际 preview ID（如需要本地开发）

预览环境可选，仅在本地 wrangler dev 时需要：

1

npm run kv:create-preview

4. 部署

1

npm run deploy

5. 本地开发

1

npm run dev

Git 提交与 CI 部署

wrangler.toml 中的 ID 如何处理？

wrangler.toml 中的 KV Namespace ID 不是敏感信息，它只是一个 Cloudflare 资源标识符，没有 API Token 就无法操作 KV 数据，可以安全地提交到 Git。

如果你希望其他开发者也能拉取代码并本地开发，clone 后按上述步骤 3 创建自己的 KV 命名空间并替换 id 即可。

提交到 Git

1
2
3
4
5
6
7
8

# 1. 初始化仓库
git init

# 2. 添加所有文件
git add .

# 3. 提交
git commit -m "feat: init openkounter"

关联远程仓库 & 部署

1
2
3
4
5
6

# 关联远程（替换为你的仓库地址）
git remote add origin https://github.com/你的用户名/openkounter.git
git push -u origin main

# 部署到 Cloudflare Workers
npm run deploy

npm run deploy 时会自动读取 wrangler.toml 中的配置（包括 KV 绑定），无需额外操作。

配置博客

在 _config.fluid.yml 中修改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

web_analytics:
  enable: true
  openkounter:
    # 替换为你的 Worker 地址
    server_url: https://openkounter.your-domain.workers.dev
    path: window.location.pathname
    ignore_local: false

footer:
  statistics:
    enable: true
    source: openkounter

post:
  meta:
    views:
      enable: true
      source: openkounter

本模块实现了 GitHub Device Authorization Flow（设备授权流），提供”扫码登录”体验。

与标准 OAuth 重定向流的区别：

完整流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  前端 (浏览器)    │         │  后端 (8081)      │         │  GitHub API      │
│  localhost:8082  │         │                  │         │                  │
└────────┬────────┘         └────────┬─────────┘         └────────┬────────┘
         │                           │                           │
         │  ① POST /device/init      │                           │
         ├──────────────────────────► │                           │
         │                           │  ② POST device/code       │
         │                           │  ───────────────────────► │
         │                           │                           │
         │                           │  ③ 返回 device_code       │
         │                           │  + user_code              │
         │                           │  + verification_uri       │
         │                           │◄───────────────────────── │
         │                           │                           │
         │  ④ 返回 {deviceCode,      │                           │
         │     userCode,             │                           │
         │     verificationUri}      │                           │
         │◄──────────────────────────┤                           │
         │                           │                           │
         │  ⑤ 渲染二维码(≈ verification_uri)                      │
         │  显示 user_code: DDB3-23AD                             │
         │                           │                           │
         │  ⑥ 用户用手机扫描二维码     │                           │
         │  或直接访问 github.com/login/device                    │
         │  输入 user_code 完成授权    │                           │
         │                           │                           │
         │  ⑦ GET /device/status     │   每 5s 轮询              │
         │  ?deviceCode=xxx          │                           │
         ├──────────────────────────► │                           │
         │                           │  ⑧ POST /login/oauth/    │
         │                           │     access_token          │
         │                           │  ───────────────────────► │
         │                           │  ◄── authorization_pending│
         │  ⑨ "等待扫码中..."        │                           │
         │◄──────────────────────────┤                           │
         │          ════════════════════════════════════          │
         │         用户手机在 GitHub 上确认授权                    │
         │          ════════════════════════════════════          │
         │                           │                           │
         │  ⑩ 再次轮询               │                           │
         ├──────────────────────────► │                           │
         │                           │  ⑪ POST /login/oauth/    │
         │                           │     access_token          │
         │                           │  ───────────────────────► │
         │                           │  ⑫ 返回 access_token     │
         │                           │◄───────────────────────── │
         │                           │                           │
         │                           │  ⑬ GET /user (获取用户信息)│
         │                           │  ───────────────────────► │
         │                           │  ◄── 返回 GitHub 用户     │
         │                           │                           │
         │                           │  ⑭ 查/创建 ShopUser       │
         │                           │  生成 JWT + refresh token │
         │                           │                           │
         │  ⑮ 返回 token + 用户信息  │                           │
         │◄──────────────────────────┤                           │
         │                           │                           │
         │  ⑯ 保存 token 到 localStorage                         │
         │  跳转到 /shop              │                           │

后端实现

1. OAuthService 接口扩展

文件: src/main/java/com/.../service/OAuthService.java

新增两个接口方法：

1
2
3
4
5

// 初始化设备流：调用 GitHub API 获取 device_code / user_code
Response initDeviceFlow();

// 轮询设备流状态：检查用户是否已授权
Response checkDeviceFlow(String deviceCode);

2. OAuthServiceImpl 实现

文件: src/main/java/com/.../service/impl/OAuthServiceImpl.java

constants

1
2
3
4
5

private static final String GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code";
private static final String GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token";
private static final String GITHUB_USER_URL = "https://api.github.com/user";
private static final String GITHUB_EMAIL_URL = "https://api.github.com/user/emails";
private static final String DEVICE_KEY_PREFIX = "weblog:device:";

initDeviceFlow()

1
2
3
4
5
6
7
8
9
10

1. POST https://github.com/login/device/code
   Body: client_id, scope=read:user,user:email
   → 返回 device_code, user_code, verification_uri, interval, expires_in

2. 将 device_code 状态存入 Redis:
   KEY: weblog:device:{deviceCode}
   VALUE: { deviceCode, status: "pending", expiresIn }
   TTL: expires_in (GitHub 指定的过期时间)

3. 返回前端: deviceCode, userCode, verificationUri, interval

Request:

1
2
3
4
5

POST https://github.com/login/device/code
Content-Type: application/x-www-form-urlencoded
Accept: application/json

client_id=xxx&scope=read:user,user:email

Response:

1
2
3
4
5
6
7

{
  "device_code": "3584d83530jskajsjas46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJJJ",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}

checkDeviceFlow()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

1. 从 Redis 获取设备流状态
2. 如果 status 已为 "success"，直接返回结果（清除 Redis key）
3. 如果 status 为 "expired"/"denied"，返回错误（清除 Redis key）
4. 否则 POST https://github.com/login/oauth/access_token
   Body: client_id, client_secret, device_code, grant_type=urn:ietf:params:oauth:grant-type:device_code

   GitHub 可能返回:
   - authorization_pending → 用户未操作，返回 status: pending
   - slow_down → 需要放慢轮询，返回 status: pending
   - expired_token → 标记为 expired，返回错误
   - access_denied → 标记为 denied，返回错误
   - access_token → 授权成功！

5. 授权成功后：
   a. 用 access_token 获取 GitHub 用户信息 (GET https://api.github.com/user)
   b. 用 access_token 获取主邮箱 (GET https://api.github.com/user/emails)
   c. 查找 ShopUser (by oauth_provider=github, oauth_id=github_id)
   d. 不存在则创建新用户，存在则更新昵称/头像
   e. 生成 JWT token + refresh token
   f. 返回 token, refreshToken, user 给前端

3. OAuthController 端点

文件: src/main/java/com/.../controller/OAuthController.java

4. RestTemplate 配置

文件: src/main/java/com/.../config/RestTemplateConfig.java

1
2
3
4
5
6
7

@Bean
public RestTemplate restTemplate() {
    SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
    factory.setConnectTimeout(10000);    // 连接超时 10s
    factory.setReadTimeout(30000);       // 读取超时 30s
    return new RestTemplate(factory);
}

5. 安全配置

在 WebSecurityConfig.java 中确保 /shop/oauth/** 路径允许匿名访问：

1

.antMatchers("/shop/oauth/**").permitAll()

6. SSL 握手失败重试

由于国内访问 GitHub 偶发 SSL 握手失败（Remote host terminated the handshake），getGitHubAccessToken() 内置重试机制：

1
2
3

int maxRetries = 3;
int retryDelayMs = 1000;
// 指数退避: 1s → 2s → 4s

同时强制走 TLSv1.2 避免某些代理/VPN 对 TLS 1.3 握手兼容性问题：

1

System.setProperty("https.protocols", "TLSv1.2");

前端实现

1. 扫码页面

文件: weblog-vue3/src/pages/frontend/shop-oauth-qrcode.vue

页面结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

┌─ 弹窗/居中容器 ──────────────────────┐
│                                      │
│     GitHub 扫码登录                    │
│     使用 GitHub App 扫描二维码完成登录  │
│                                      │
│         ┌───────────────┐            │
│         │               │            │
│         │  二维码图片    │            │
│         │  220x220      │            │
│         │               │            │
│         └───────────────┘            │
│                                      │
│        输入以下代码                    │
│        ┌──────────────┐              │
│        │  DDB3-23AD   │              │
│        └──────────────┘              │
│                                      │
│  或访问 https://github.com/login/     │
│  device 输入以上代码完成授权            │
│                                      │
│  ⟳ 等待扫码中...                      │
│                                      │
│  [取消]        [刷新二维码]            │
└──────────────────────────────────────┘

关键逻辑

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// 1. 初始化设备流
async function initDevice() {
  loading.value = true
  const res = await fetch('/shop/oauth/device/init', { method: 'POST' })
  const json = await res.json()
  const data = json.data

  deviceCode.value = data.deviceCode
  userCode.value = data.userCode
  verificationUri.value = data.verificationUri

  // ★ 先切到二维码视图，让 canvas 出现在 DOM 中
  loading.value = false
  await nextTick()  // 等待 DOM 更新，确保 canvas 已渲染

  // 此时 canvas 在 DOM 中了，绘制 QR 码
  await QRCode.toCanvas(qrCanvas.value, data.verificationUri, {
    width: 220,
    margin: 2
  })

  startPolling()  // 开始轮询
}

// 2. 轮询设备状态
async function pollDevice() {
  const res = await fetch('/shop/oauth/device/status?deviceCode=' + deviceCode.value)
  const json = await res.json()

  if (json.data?.token) {
    // 登录成功！保存 token 并跳转
    setShopTokens(json.data.token, json.data.refreshToken)
    router.replace('/shop')
    return
  }
  // status: pending → 继续轮询
  scheduleNextPoll()
}

注意事项

• loading 切换时机：必须先 loading = false 让 canvas 渲染到 DOM，再用 nextTick() 等待，否则 qrCanvas ref 为 null，QR 码画不上去
• 轮询间隔从 GitHub 返回的 interval 字段获取（通常 5s）
• 二维码用 qrcode npm 包（v1.5.4）的 QRCode.toCanvas() 渲染到 <canvas> 元素

2. 登录页入口

文件: weblog-vue3/src/pages/frontend/shop-login.vue

在 GitHub 按钮旁边添加扫码入口：

1
2
3
4
5
6
7

<el-button @click="goQrcode">扫码</el-button>

<script>
function goQrcode() {
  router.push('/shop/auth/qrcode')
}
</script>

同时增加 OAuth 错误显示逻辑：

1
2
3
4
5

// 检测 URL 中的 oauth_error 参数
if (route.query.oauth_error) {
  ElMessage.error('GitHub 登录失败: ' + route.query.oauth_error)
  router.replace('/shop/auth')  // 清除 URL 参数
}

3. 路由配置

文件: weblog-vue3/src/router/index.js

1
2
3
4
5

{
  path: '/shop/auth/qrcode',
  component: ShopOAuthQRCode,
  meta: { title: '扫码登录' }
}

踩坑记录

1. GitHub OAuth App 须开启 Device Flow

现象: 调用 POST /login/device/code 返回 400

1

{"error":"device_flow_disabled","error_description":"Device Flow must be explicitly enabled for this App"}

解决: 去 GitHub Settings → Developer settings → OAuth Apps → 选择你的 App → 勾选 “Enable Device Flow” → Save

2. RestTemplate 在 4xx 响应时抛异常

现象: GitHub 返回 HTTP 400，但 restTemplate.postForEntity() 在读取响应体之前就抛出 HttpClientErrorException

解决: 在 initDeviceFlow() 的 catch 中先捕获 HttpClientErrorException，从 e.getResponseBodyAsString() 解析错误 JSON 体

3. SSL 握手失败（国内网络问题）

现象: 访问 https://github.com/login/oauth/access_token 时 Java 报错

1

javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake

原因:

• 国内访问 GitHub 网络不稳定，中间设备可能中断 TLS 连接
• 某些代理/VPN 设备对 TLS 1.3 握手兼容性不好

解决:

• 强制使用 TLSv1.2: System.setProperty("https.protocols", "TLSv1.2")
• 添加重试机制：getGitHubAccessToken() 最多重试 3 次，指数退避

4. 前端 Canvas ref 为 null 导致 QR 码空白

现象: 二维码区域显示了（有边框），但里面没有二维码图案

原因: 代码中 <canvas ref="qrCanvas"> 在 v-if="loading" 条件下不存在。API 返回数据后，代码先改了 deviceCode 等变量但没改 loading，执行 nextTick() 时 DOM 里还是加载状态，canvas 没渲染出来，qrCanvas.value = null

解决: 绘制 QR 码前先 loading.value = false 让 DOM 切换到二维码视图，再 await nextTick() 确保 canvas 已就绪。

5. OAuth callback 中 base64 URL 安全编码问题

现象: 前端 atob() 解码用户信息时报错

原因: 后端 Base64.getUrlEncoder() 使用了 URL 安全的 Base64（- 和 _ 替代 + 和 /），前端 atob() 不认识这种变体

解决: 解码前替换字符：

1
2

const standardBase64 = data.user.replace(/-/g, '+').replace(/_/g, '/')
const userStr = atob(standardBase64)

配置项

application.yml

1
2
3
4
5
6

oauth:
  github:
    client-id: Ov23li0zJcTQdkklkswc
    client-secret: xxxxxxxxx
    redirect-uri: http://localhost:8081/shop/oauth/callback/github
    frontend-url: http://localhost:8082

相关依赖

1
2
3
4
5
6
7
8

<!-- spring-web（内含 RestTemplate） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Redis（存储设备流状态） -->
<!-- 通过 spring-boot-starter-data-redis 引入 -->

测试指南

手动测试

1. 确保 Vite 前端运行在 localhost:8082，后端运行在 localhost:8081
2. 访问 http://localhost:8082/#/shop/auth
3. 点击”扫码”按钮
4. 页面显示二维码和 user_code
5. 用手机扫描二维码，或访问 https://github.com/login/device 输入 user_code
6. 在手机上确认授权
7. 浏览器自动跳转到商城首页，登录成功

后端 API 直接验证

1
2
3
4
5

# 1. 初始化设备流
curl -X POST http://localhost:8081/shop/oauth/device/init

# 2. 轮询状态（替换 deviceCode）
curl "http://localhost:8081/shop/oauth/device/status?deviceCode=xxx"