企业官网建设流程全解析

1. 项目概述：为什么“OpenRouter 快速访问近期 AI 会话”这件事值得单独写一篇深度实操笔记？

OpenRouter 这个名字最近在开发者、AI 工具链实践者和轻量级 AI 应用搭建者圈子里出现频率明显升高。它不是模型本身，而是一个典型的“AI 模型路由层”——你可以把它理解成 AI 世界的“快递中转站”：上游对接 Anthropic、Google、Meta、Mistral、Cohere 等二十多家厂商的闭源与开源大模型 API；下游则统一提供标准化的 OpenAI 兼容接口（/v1/chat/completions），让开发者不用为每个模型重写适配逻辑。但真正让它从“技术中间件”跃升为高频使用工具的关键，并不在于它能调哪个模型、价格便宜几美分，而在于它悄悄解决了一个被长期忽视却极其真实的痛点：会话状态的可追溯性与上下文连续性管理。

你有没有遇到过这些场景？

• 在网页端反复提问同一个模型，想回溯3分钟前那句关键提示词，却发现历史记录只保留最近5条，且无法导出；
• 用 curl 或 Postman 调 OpenRouter 的 API 写自动化脚本，每次请求都是无状态的，想复现某次失败的对话，只能靠手动记日志；
• 给团队成员分享一个调试中的 prompt 效果，对方打开链接看到的却是最新一次会话，而不是你截图里那个精准生效的上下文；
• 做 AI Agent 测试时，需要对比不同模型对同一段多轮对话的响应差异，但每个模型的会话 ID 完全隔离，根本没法横向对齐。

这些都不是功能缺陷，而是架构设计上的“默认省略”——OpenRouter 本身不托管会话，它的核心职责是转发请求、计费、限流、负载均衡。但用户要的从来不是“转发”，而是“可复现的智能交互过程”。所谓“快速访问近期 AI 会话”，本质是在 OpenRouter 的无状态 API 架构之上，构建一层轻量、可靠、可嵌入的会话状态桥接层。它不改变 OpenRouter 的任何行为，也不依赖其后台数据库（事实上官方并不开放会话存储接口），而是通过客户端侧的请求特征提取 + 本地缓存策略 + 标准化元数据打标，把散落在 HTTP 请求流里的“会话意图”重新聚合成可检索、可跳转、可复用的实体。

我从去年底开始在三个不同规模的内部项目中落地这套方案：一个是面向销售团队的客户问答助手（需保存每轮客户追问与模型应答）；一个是研发侧的 Prompt 工程协作平台（要求多人能基于同一段会话 ID 进行迭代评论）；还有一个是教育类 AI 助教的课堂对话存档系统（需按课程ID+学生ID自动归档）。三套系统底层都复用同一套会话索引逻辑，平均将“找回上次对话”的操作步骤从 7 步压缩到 2 步，历史会话加载延迟稳定控制在 80ms 以内。这不是炫技，而是把 AI 工具真正当成“工作流组件”来用的必要基建。

关键词“OpenRouter”“AI”“会话”在这里不是泛泛而谈的技术标签，而是精确指向三个不可割裂的维度：路由层协议兼容性（OpenRouter）、语义交互单元（AI）、状态锚点（会话）。下文所有技术细节，都将围绕这三者的交集展开——不讲大模型原理，不堆API参数列表，只聚焦“如何让每一次 AI 对话，都像微信聊天记录一样，点开就能续上”。

2. 核心设计思路：为什么不用官方 SDK、不依赖后端存储、也不做浏览器插件？

拿到“快速访问近期 AI 会话”这个需求，第一反应往往是查 OpenRouter 官方文档找 history API，或者翻 GitHub 看有没有现成的 SDK 支持会话管理。我试过——官方根本没有这类接口。OpenRouter 的 API 设计哲学非常清晰：它只负责把你的请求发给对应模型，并把响应原样返回。所有状态管理（包括 token 使用统计、模型调用频次、甚至错误重试逻辑）都由调用方自行承担。这意味着，任何试图在服务端加一层“会话代理”的方案，都会面临两个硬伤：一是违背 OpenRouter 的无状态设计原则，增加运维复杂度；二是引入额外延迟，对低延迟敏感的实时交互场景（比如语音转文字后的即时问答）造成体验断层。

另一个常见思路是做浏览器插件，监听 fetch/XHR 请求，自动捕获 request.body 和 response.body，再存到 indexedDB。这条路我跑了三个月，最终放弃。原因很实在：

• 插件权限模型越来越严，Chrome 115+ 默认禁用 activeTab 权限下的跨域请求拦截，必须申请 host_permissions，而 OpenRouter 的域名（openrouter.ai）属于高风险权限，审核通过率低于 12%；
• 更致命的是，插件无法区分“真实用户会话”和“后台预加载请求”——比如页面初始化时自动调用 /models 接口获取模型列表，这类请求如果也被存为“会话”，会严重污染历史记录；
• 最后，插件方案天然绑定浏览器环境，而我们大量 AI 调用发生在 Python 脚本、Node.js CLI 工具、甚至嵌入式设备的轻量 HTTP 客户端中，插件完全失效。

所以最终确定的方案是：在调用方代码中植入轻量级会话上下文管理器（Session Context Manager），通过标准化的请求头注入 + 响应体解析 + 本地持久化，实现跨环境、跨语言、零依赖的会话锚定。具体来说，有四个设计锚点：

2.1 锚点一：用 X-Session-ID 替代传统 cookie 机制

OpenRouter 官方文档明确说明：“所有请求必须携带 Authorization: Bearer 头”。我们在此基础上，约定新增一个请求头：X-Session-ID: <uuid>。这个 UUID 不是随机生成，而是基于当前会话的语义指纹计算得出——例如，对首次请求，取sha256(prompt + model_name + temperature)的前12位；对后续请求，则沿用首次生成的 ID，并在请求体 messages 数组末尾追加一条 system 角色消息：“[SESSION_ID: xxx]”。这样做的好处是：

• 服务端完全无感，OpenRouter 会原样透传该 header，不影响任何现有逻辑；
• 客户端可通过该 header 快速定位同一会话的所有请求；
• 即使请求被重试或失败，只要 prompt 和参数不变，生成的 session ID 就不变，保证可复现性。

2.2 锚点二：响应体结构化增强，而非简单存 raw JSON

OpenRouter 返回的 JSON 结构与 OpenAI 完全一致，但缺少会话元信息。我们在收到响应后，不直接存 response.json()，而是构造一个增强对象：

{ "session_id": "a1b2c3d4e5f6", "timestamp": 1717023456789, "request": { "model": "anthropic/claude-3-haiku", "messages": [...], "temperature": 0.7 }, "response": { "id": "chatcmpl-xxx", "choices": [...], "usage": {...} }, "metadata": { "latency_ms": 1247, "cached": false, "provider": "anthropic" } }

这个结构的关键在于metadata字段——它不是从 OpenRouter 返回的，而是客户端在发起请求前记录 start time，收到响应后计算差值得到。cached字段则通过检查响应头X-Cache: HIT判断（OpenRouter 对部分模型启用了边缘缓存）。这些字段虽小，但在后续做会话质量分析时价值巨大：比如你想筛选“耗时超过2秒且未命中缓存”的会话，直接查 metadata 就行，不用解析原始 response。

2.3 锚点三：本地存储采用 LevelDB + TTL 策略，而非 localStorage

很多人第一反应是用 localStorage 存会话。但实际测试发现，当单个会话记录超过 50KB（常见于长上下文或多图 base64 编码），localStorage 的序列化/反序列化性能急剧下降，100 条会话就可能卡顿。我们改用 level （Node.js）或 idb （浏览器）作为底层存储引擎，核心优势有三点：

• 支持流式读写，避免一次性加载全部会话到内存；
• 可设置 TTL（time-to-live），比如自动清理 7 天前的会话，防止磁盘爆满；
• 提供 keyPrefix 查询，例如db.iterator({ gte: 'session_202405_' })可快速获取某天所有会话，比遍历全量数据快 17 倍。

2.4 锚点四：会话生命周期由调用方显式控制，而非自动绑定页面会话

这是最容易被忽略的设计点。很多方案默认把“一次页面打开”当作一个会话周期，但现实远比这复杂：

• 用户可能在 Tab A 问产品问题，在 Tab B 问技术问题，两者应隔离；
• 同一 Tab 内，用户可能先问“帮我写 Python 脚本”，再切到“总结会议纪要”，这两个主题显然不该混在一个会话里；
• 更常见的是，用户点击“新建对话”按钮，但前端没清空 messages 数组，导致新提问叠加在旧上下文上，产生幻觉。

因此，我们强制要求：每次调用 OpenRouter API 前，必须显式调用sessionManager.startNew()或sessionManager.resume(id)。startNew 会生成新 session ID 并清空当前上下文；resume 则加载指定 ID 的历史 messages 并追加新提问。这个动作不依赖 URL hash、不依赖 localStorage key，而是由业务逻辑决定——比如在 Chat UI 中，“+ 新对话”按钮背后就是 startNew()，而点击历史列表某条记录则是 resume(id)。这种显式控制，让会话边界变得绝对清晰。

提示：不要试图用 URL 参数（如 ?session=a1b2c3）来传递会话 ID。实测发现，当用户复制链接分享给同事时，对方打开后虽然能看到相同 ID，但因本地没有对应缓存，仍会触发空会话。真正的会话可移植性，必须依赖导出/导入机制，这点在第4节详述。

3. 实操细节拆解：从零构建会话管理器的 7 个关键环节

现在进入最硬核的部分：如何把上述设计落地为可运行的代码。以下所有示例均基于 TypeScript（浏览器环境）和 Python（CLI 环境）双实现，确保你在任何技术栈中都能复用核心逻辑。我们不假设你已安装特定框架，所有依赖均为轻量级标准库或通用包。

3.1 环境准备：最小依赖清单与版本锁定

先明确一个前提：本方案不修改 OpenRouter 的任何服务端逻辑，所有改动都在调用方。因此，你需要准备两类环境：

浏览器端（React/Vue/Svelte 项目）：

• 必装：idb@7.1.1（IndexedDB 封装，比原生 API 易用 10 倍）
• 可选：nanoid@5.0.7（生成短 ID，比 UUID 更节省存储空间）
• 禁用：任何全局拦截 fetch 的 polyfill（如 whatwg-fetch），会干扰原生 Request/Response 对象的 integrity

Python 端（CLI 或 FastAPI 后端）：

• 必装：leveldb@1.20.0（注意不是 levelup，而是纯 Python binding）
• 必装：python-dotenv==1.0.0（安全读取 OPENROUTER_API_KEY）
• 禁用：requests库的 session 对象（它自带 cookie jar，会与我们的 X-Session-ID 冲突）

注意：OpenRouter 官方推荐的openrouter-pythonSDK（v0.2.3）默认启用 requests.Session，必须 patch。实测方法是在 import 后插入：

from openrouter import OpenRouter # 禁用 SDK 内置 session OpenRouter._session = None

否则 SDK 会自动添加 cookie 头，导致 X-Session-ID 被覆盖。

3.2 Session ID 生成算法：语义指纹 vs 随机 UUID 的实战权衡

Session ID 是整个方案的基石，它必须满足三个条件：唯一性、可复现性、可读性。我们测试过四种生成策略，最终选定“语义哈希 + 时间戳截断”组合：

最后一行就是我们采用的公式。其中ts[-4:]取时间戳毫秒的后4位（如 1717023456789 →6789），作用是：当用户连续发送两个完全相同的 prompt（比如误触两次发送），避免生成相同 ID 导致后一次覆盖前一次。实测 10 万次并发请求，冲突率低于 0.0003%。

Python 实现示例：

import hashlib import time def generate_session_id(prompt: str, model: str, temperature: float = 0.7) -> str: # 标准化输入：去除首尾空格，统一换行符 clean_prompt = prompt.strip().replace('\r\n', '\n').replace('\r', '\n') # 构造指纹字符串 fingerprint = f"{clean_prompt}|{model}|{temperature:.1f}" # 生成哈希并截取 hash_part = hashlib.sha256(fingerprint.encode()).hexdigest()[:8] # 添加时间戳后缀 ts_suffix = str(int(time.time() * 1000))[-4:] return f"{hash_part}{ts_suffix}" # 示例：相同 prompt 不同模型 → 不同 ID print(generate_session_id("hello", "anthropic/claude-3-haiku")) # a1b2c3d41234 print(generate_session_id("hello", "google/gemini-pro")) # e5f6g7h81234

这个函数必须在调用 OpenRouter 前执行，且结果要同时注入X-Session-ID头和 request body 的 system message 中，确保两端一致。

3.3 请求头注入与请求体增强：两处必须同步修改的位置

OpenRouter 的/v1/chat/completions接口接受标准 OpenAI 格式，但我们要在不破坏兼容性的前提下注入会话信息。关键修改点只有两处：

第一处：HTTP 请求头

// 浏览器端 fetch 调用 const response = await fetch("https://openrouter.ai/api/v1/chat/completions", { method: "POST", headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", "X-Session-ID": sessionId, // ← 必加！ }, body: JSON.stringify({ model: "anthropic/claude-3-haiku", messages: [ { role: "system", content: "[SESSION_ID: a1b2c3d41234]" }, // ← 必加！ { role: "user", content: "你好" } ], temperature: 0.7 }) });

第二处：请求体 messages 数组
注意 system message 必须放在 messages 数组首位，且内容严格为[SESSION_ID: xxx]格式。OpenRouter 不会解析这个字符串，但它会被完整返回到 response.choices[0].message.content 中，成为我们校验会话完整性的依据。实测发现，如果放在 user message 之后，某些模型（如 llama-3-70b）会将其当作普通指令执行，导致输出异常。

Python 端等效实现：

import httpx def make_openrouter_request(session_id: str, prompt: str): url = "https://openrouter.ai/api/v1/chat/completions" headers = { "Authorization": f"Bearer {os.getenv('OPENROUTER_API_KEY')}", "Content-Type": "application/json", "X-Session-ID": session_id # ← 同样必加 } data = { "model": "anthropic/claude-3-haiku", "messages": [ {"role": "system", "content": f"[SESSION_ID: {session_id}]"}, {"role": "user", "content": prompt} ], "temperature": 0.7 } return httpx.post(url, headers=headers, json=data)

提示：不要用X-Request-ID替代X-Session-ID。前者是 OpenRouter 用于追踪单次请求的内部 ID，每次重试都会变，且不保证跨模型一致；后者是我们定义的业务 ID，生命周期与用户意图绑定。

3.4 响应解析与结构化存储：如何从 raw JSON 提炼有效元数据

收到 OpenRouter 响应后，不能直接存 response.json()，必须做三件事：提取 session ID、计算元数据、构造增强对象。以下是浏览器端完整流程：

async function handleOpenRouterResponse( response: Response, startTime: number, sessionId: string, requestPayload: any ): Promise<void> { const endTime = Date.now(); const rawJson = await response.json(); // 1. 校验 session ID 是否存在于响应中（防御性编程） const hasSessionTag = rawJson?.choices?.[0]?.message?.content?.includes( `[SESSION_ID: ${sessionId}]` ); if (!hasSessionTag) { console.warn(`Session ID ${sessionId} not found in response - possible corruption`); return; } // 2. 提取关键元数据 const latencyMs = endTime - startTime; const cached = response.headers.get("X-Cache") === "HIT"; const provider = response.headers.get("X-Provider") || "unknown"; // 3. 构造增强对象并存入 IDB const enhancedRecord = { session_id: sessionId, timestamp: endTime, request: requestPayload, response: rawJson, metadata: { latency_ms: latencyMs, cached, provider, status_code: response.status, size_bytes: response.headers.get("Content-Length") || 0 } }; // 存入 IDB（使用 idb 库） const db = await openDB("openrouter-sessions", 1, { upgrade(db) { db.createObjectStore("sessions", { keyPath: "session_id" }); } }); const tx = db.transaction("sessions", "readwrite"); await tx.store.put(enhancedRecord); await tx.done; }

Python 端对应逻辑更简洁（因无需处理 DOM）：

def save_session_record(session_id: str, request_data: dict, response_json: dict, start_time: float, response: httpx.Response): end_time = time.time() * 1000 latency_ms = int(end_time - start_time * 1000) # 提取 provider（从响应头） provider = response.headers.get("X-Provider", "unknown") cached = response.headers.get("X-Cache") == "HIT" record = { "session_id": session_id, "timestamp": int(end_time), "request": request_data, "response": response_json, "metadata": { "latency_ms": latency_ms, "cached": cached, "provider": provider, "status_code": response.status_code } } # 存入 LevelDB（key 为 session_id） db = plyvel.DB('./sessions.db', create_if_missing=True) db.put(session_id.encode(), json.dumps(record, ensure_ascii=False).encode()) db.close()

这个过程耗时通常 < 3ms，远低于网络延迟，不会成为性能瓶颈。

3.5 会话检索与加载：支持模糊搜索、时间范围、模型筛选的三级索引

存储只是第一步，快速找到目标会话才是“快速访问”的核心。我们构建了三层索引机制：

第一层：主键索引（session_id）
直接通过db.get(session_id)获取单条记录，响应时间 < 0.5ms。适用于“点击历史列表查看详情”场景。

第二层：时间范围索引（timestamp）
在 LevelDB 中，我们额外维护一个by_timestamp子库，key 为ts:1717023456789:session_id，value 为空。查询“今天所有会话”时，用db.iterator({ gte: 'ts:1717023456789', lte: 'ts:1717109856789' })扫描，再从主库批量 get。实测 10 万条记录下，5 分钟范围查询耗时 12ms。

第三层：内容模糊索引（prompt snippet）
对每条记录，提取 prompt 的前 50 字符 + 后 50 字符（去除空格和换行），生成snippet字段。例如：
prompt = "请帮我分析这份财报，重点关注Q3营收增长率和毛利率变化...（2000字）"
→snippet = "请帮我分析这份财报重点关注Q3营收增长率和毛利率变化"
然后存为snippet:请帮我分析这份财报重点关注Q3营收增长率和毛利率变化 → session_id。用户搜索“财报”时，直接查db.get('snippet:财报')，再做字符串匹配过滤。

浏览器端搜索函数示例：

async function searchSessions(query: string, options: { from?: number; to?: number; model?: string; } = {}) { const db = await openDB("openrouter-sessions", 1); const tx = db.transaction("sessions", "readonly"); const store = tx.store; // 先查时间范围 let keys: string[] = []; if (options.from && options.to) { const range = IDBKeyRange.bound(options.from, options.to); keys = await store.getAllKeys(range); } else { keys = await store.getAllKeys(); } // 再过滤 model 和 query const results = await Promise.all( keys.map(async key => { const record = await store.get(key); const matchModel = !options.model || record.request.model.includes(options.model); const matchQuery = !query || record.request.messages?.[1]?.content?.toLowerCase().includes(query.toLowerCase()); return matchModel && matchQuery ? record : null; }) ); return results.filter(Boolean); }

这个设计让搜索响应时间稳定在 50ms 内，即使数据库有 5000 条记录。

3.6 会话导出与导入：JSONL 格式为何比 ZIP 更适合跨环境迁移

当用户需要把会话分享给同事，或迁移到新设备时，“导出”功能必不可少。我们放弃常见的 JSON 或 ZIP 方案，选择JSONL（JSON Lines）格式，原因如下：

• 流式处理友好：JSONL 每行一个 JSON 对象，可逐行读取，内存占用恒定 O(1)，而完整 JSON 需一次性 load 到内存，1000 条会话就可能吃掉 200MB；
• 增量导入安全：导入时逐行 parse，某一行格式错误（如多了一个逗号）只导致该行失败，不影响其余数据；
• Git 友好：JSONL 文件 diff 清晰，可直接看到哪条会话被新增/修改；
• 跨语言通用：Python 的jsonlines、Node.js 的jsonlines、甚至 Bash 的jq -r '.session_id' file.jsonl都原生支持。

导出函数（浏览器端）：

async function exportSessions(sessionIds: string[]) { const db = await openDB("openrouter-sessions", 1); const tx = db.transaction("sessions", "readonly"); const store = tx.store; const lines: string[] = []; for (const id of sessionIds) { const record = await store.get(id); if (record) { // 移除二进制字段（如 base64 图片），只保留文本 const safeRecord = { ...record, response: { ...record.response, choices: record.response.choices.map((c: any) => ({ ...c, message: { ...c.message, content: c.message.content?.substring(0, 5000) || "" // 截断超长内容 } })) } }; lines.push(JSON.stringify(safeRecord, null, 0)); // 0 表示不缩进，减小体积 } } const blob = new Blob(lines, { type: "application/jsonl" }); const url = URL.createObjectURL(blob); const a = document.createElement("a"); a.href = url; a.download = `openrouter-sessions-${Date.now()}.jsonl`; a.click(); URL.revokeObjectURL(url); }

导入函数（Python 端）：

def import_sessions(file_path: str): db = plyvel.DB('./sessions.db', create_if_missing=True) with open(file_path, 'r', encoding='utf-8') as f: for line_num, line in enumerate(f, 1): try: record = json.loads(line.strip()) if 'session_id' not in record: print(f"Warning: line {line_num} missing session_id, skipped") continue db.put(record['session_id'].encode(), json.dumps(record, ensure_ascii=False).encode()) except json.JSONDecodeError as e: print(f"Error parsing line {line_num}: {e}") continue db.close()

实测 1000 条会话的 JSONL 文件仅 8.2MB，而同等数据的 ZIP+JSON 达 12.7MB，且导入速度提升 3.2 倍。

3.7 UI 层集成：如何在 Chat UI 中无缝嵌入会话历史面板

最后一步，是把技术能力转化为用户体验。我们设计了一个极简的会话历史面板，集成在 Chat UI 右侧（宽度 320px），包含三个 Tab：

• Recent：按时间倒序显示最近 20 条会话，每条显示session_id前8位、prompt 截断（30字）、响应耗时、模型图标；
• Search：带 debounce 的实时搜索框，支持model:claude、after:2024-05-20等语法；
• Import/Export：拖拽上传 JSONL 文件，或点击导出当前筛选结果。

关键交互逻辑：

• 点击某条会话 → 自动调用sessionManager.resume(id)，清空当前输入框，加载该会话全部 messages，并滚动到底部；
• 长按会话项 → 弹出菜单：复制 session_id、导出单条、删除；
• 新建对话时，面板自动滚动到顶部，确保新会话可见。

CSS 采用 CSS-in-JS 方案，核心样式仅 42 行，适配深色/浅色模式：

.history-panel { border-left: 1px solid var(--border-color); overflow-y: auto; height: 100%; } .history-item { padding: 12px 16px; border-bottom: 1px solid var(--border-color); cursor: pointer; transition: background 0.1s; } .history-item:hover { background: var(--hover-bg); } .history-item:last-child { border-bottom: none; } .session-id { font-family: monospace; font-size: 0.85em; color: var(--text-secondary); }

这个面板不依赖任何 UI 框架，React/Vue/Svelte 项目均可通过自定义 Hook 或 Composition API 复用。

4. 实操避坑指南：12 个踩过的坑与对应的解决方案

再完美的设计，落地时也会遇到意料之外的问题。以下是我在三个项目中累计踩过的 12 个典型坑，按发生频率排序，每个都附带可立即执行的解决方案。

4.1 坑点1：OpenRouter 的 X-Cache 头在某些模型上不返回，导致 cached 字段误判

现象：调用google/gemini-pro时，响应头始终没有X-Cache，所有请求都被标记为cached: false，但实际上部分请求明显更快（< 300ms）。
根因：OpenRouter 对 Google 模型的缓存策略是 bypass cache，但未透传X-Cache头。
解决方案：增加 fallback 判断逻辑——当X-Cache缺失时，若latency_ms < 500且response.usage.total_tokens < 200，则 heuristic 标记为cached: true。实测准确率达 92%。

4.2 坑点2：移动端 Safari 的 IndexedDB 事务在页面后台时被中断

现象：iOS 用户切换 Tab 后再切回来，会话保存失败，控制台报AbortError: Transaction timed out。
根因：Safari 为省电会暂停后台页面的 IDB 事务。
解决方案：在visibilitychange事件中监听页面状态，若document.hidden为 true，则暂停写入，待visibilitychange事件触发后再批量 flush。代码片段：

let pendingWrites: any[] = []; document.addEventListener('visibilitychange', () => { if (document.hidden) return; // 页面回到前台，执行积压写入 pendingWrites.forEach(write => db.put(write)); pendingWrites = []; });

4.3 坑点3：LevelDB 在 Windows 上编译失败，报错fatal error C1083: Cannot open include file: 'windows.h'

现象：Python 项目在 Windows 开发机上pip install plyvel失败。
根因：plyvel 依赖 leveldb C++ 库，Windows 需要 Visual Studio Build Tools。
解决方案：改用纯 Python 实现的diskcache库替代，API 完全兼容：

from diskcache import Cache cache = Cache('./sessions_cache') cache.set(session_id, record) # 用法一致

diskcache 在 Windows/macOS/Linux 上表现一致，且支持 TTL。

4.4 坑点4：用户复制 prompt 时带入不可见字符（如 U+200B 零宽空格），导致 session ID 计算不一致

现象：同一段文字，用户从网页复制粘贴后，生成的 session ID 与手动输入不同。
根因：某些网站会在文本中插入 Unicode 零宽字符用于排版。
解决方案：在generate_session_id函数中，预处理 prompt：

def normalize_prompt(prompt: str) -> str: # 移除所有零宽字符 import re prompt = re.sub(r'[\u200b-\u200f\u202a-\u202e]', '', prompt) # 移除 BOM if prompt.startswith('\ufeff'): prompt = prompt[1:] return prompt.strip()

4.5 坑点5：OpenRouter 的 rate limit 响应体不包含 Retry-After 头，导致重试逻辑混乱

现象：触发 429 错误后，SDK 默认立即重试，造成雪崩。
根因：OpenRouter 返回{"error": {"message": "Rate limit exceeded"}}，但无标准重试头。
解决方案：解析 error.message，若含"Rate limit"，则固定等待 1 秒后重试（OpenRouter 文档注明基础限流为 1 QPS）。代码：

if response.status_code == 429: error_msg = response.json().get("error", {}).get("message", "") if "Rate limit" in error_msg: time.sleep(1) return make_request(...) # 递归重试

4.6 坑点6：浏览器端 fetch 的 redirect: 'follow' 导致 X-Session-ID 在重定向后丢失

现象：某些地区用户访问 openrouter.ai 时被重定向到 cdn 域名，自定义 header 消失。
根因：fetch 规范规定，重定向时除少数安全 header 外，其他 header 会被丢弃。
解决方案：强制设置redirect: 'manual'，手动处理重定向：

const response = await fetch(url, { redirect: 'manual', headers: { 'X-Session-ID': sessionId } }); if (response.redirected) { // 手动发起新请求，带上 header return fetch(response.url, { headers: { 'X-Session-ID': sessionId } }); }

4.7 坑点7：Python 的 httpx.AsyncClient 在高并发下 connection pool 耗尽

现象：并发 > 50 时，出现 `http