笔记 · 03

WebAI2API 部署与 ChatSEU 适配器开发实战

WebAI2API 部署与 ChatSEU 适配器开发实战教程

⚠️ 使用前必读:安全与合规红线

本文档仅供个人本地学习与研究使用。部署或使用前,请确认你已理解并遵守以下约束。

一、严禁将 API 暴露到公网 - 只允许监听 127.0.0.1(默认值),不要改成 0.0.0.0,也不要对外开放端口。 - 严禁端口映射、内网穿透(frp / ngrok / cloudflared 等)、公网域名解析、反向代理。 - server.auth 只是简单鉴权,不能当作公网安全边界。一旦暴露,等于把校园账号的访问能力交给互联网。

二、严禁对学校共用资源执行攻击性行为 - 禁止对 ChatSEU、统一身份认证(auth.seu.edu.cn)等校园系统做压力测试、并发轰炸、批量爬取、漏洞扫描或任何形式的干扰。 - 禁止多账号轮换、账号共享、绕过频率限制或风控、伪造请求批量调用。 - 自动化调用须保持个人正常使用强度(低频、单账号、串行),不得影响其他师生使用。

三、合规与责任 - 遵守学校信息化服务条款与相关法律法规;抓包与自动化仅限你有权访问的数据。 - 因滥用导致的账号封禁、纪律处分或法律责任,由使用者自行承担。

四、本地数据保护 - 登录态(data/camoufoxUserData)与请求历史(data/history)保存在本机,含个人身份凭据,不要分享、上传或提交到公开仓库。 - 不要把 data/config.yaml 里的 server.auth 密钥贴到公开场合。

本文基于一次真实的本地部署过程整理:从零跑通 WebAI2API → 完成东南大学 ChatSEU 登录 → 抓包分析其 SSE 协议 → 编写适配器 → 处理 ABI 不匹配、端口冲突、浏览器 profile 锁、系统 PATH 损坏、回复重复等一系列问题。 所有命令与路径均按实际环境校验过,可直接照做。

目录


0. 你能得到什么

完成全部步骤后:

  1. 本地跑起一个 OpenAI 兼容网关:http://localhost:3000/v1
  2. 通过它调用 东南大学 ChatSEU(浏览器自动化,无官方 API 也能用)
  3. 自己新增站点适配器,把任意网页版 AI 接进来
  4. 在 Agents 客户端 / 任意 OpenAI 客户端里直接选模型使用
  5. 具备一套排错能力:能定位 ABI、端口、profile 锁、SSE 解析类问题

1. 原理与架构

1.1 WebAI2API 是什么

把「网页版 AI」包装成「OpenAI 兼容 API」的网关:

OpenAI 客户端 ──HTTP──> 本地网关 ──Playwright──> 真实浏览器 ──> 网页版 AI
                          │                          │
                          └── 适配器解析请求/响应 ────┘
  • 对外:/v1/models、/v1/chat/completions(支持 stream)
  • 对内:每个站点一个适配器(adapter),负责「打开页面 → 输入问题 → 抓取回答」

1.2 关键组件

组件 位置 职责
入口 supervisor.js 看门狗:拉起子服务、崩溃自动重启、提供 IPC 停止通道
服务 src/server/server.js HTTP 服务、鉴权、路由
请求解析 src/server/api/openai/parse.js 把 OpenAI messages 拼成「虚拟上下文」
队列 src/server/queue.js 并发控制、心跳、结果落库
适配器注册表 src/backend/adapter/*.js 扫描目录、加载 manifest、暴露模型列表
浏览器引擎 src/backend/engine/ Camoufox 启动、指纹、页面工具
数据 data/ 配置、浏览器 profile、日志、历史库

1.3 一次请求的完整链路

POST /v1/chat/completions
  → 鉴权(server.auth)
  → parseTextRequest:system / 历史 / 当前输入 → 拼成最终 prompt
  → 队列(maxConcurrent=1 时串行)
  → worker 执行 adapter.generate()
       → page.goto(入口)
       → 找输入框 → 输入 → 回车
       → waitForResponse 抓 SSE
       → 解析 token → 还原文本
  → 返回 JSON 或 SSE 流
  → 写入 history 库

理解这条链路后,排错就有方向:哪一步断了,日志就停在哪一步。


2. 环境准备(两个必查的坑)

2.1 系统要求

项 要求
操作系统 Windows 10/11、macOS、Linux 均可
Node.js 20+,本教程固定使用 v24(原因见 2.2)
内存 ≥ 8 GB(Camoufox 常驻约 500 MB~1 GB)
磁盘 ≥ 2 GB(浏览器 + 依赖)
网络 能访问目标站点(ChatSEU 需校园网或 VPN)

2.2 坑之一:Node 版本必须与原生模块 ABI 对齐

better-sqlite3 是原生模块,编译时绑定 Node 的 ABI 版本:

Node ABI
20.x 115
22.x 127
24.x 137

现象:日志里出现

NODE_MODULE_VERSION 127. This version of Node.js requires NODE_MODULE_VERSION 137

后果:历史库初始化失败 → 浏览器指纹生成失败 → 工作池全部初始化失败 → 安全模式(WebUI 能开,API 不可用)。

正确做法(二选一,不要混用)

  • 方案 A(推荐):统一用系统 Node,并让所有启动脚本显式指定: bat set "NODE_EXE=C:\Program Files\nodejs\node.exe" 再按该 Node 的 ABI 下载对应 better_sqlite3.node。
  • 方案 B:全程用 IDE 内置的 Node,不要用系统 Node 启动。

本教程采用方案 A,并已把二进制替换为 ABI 137。

替换预编译二进制的通用命令(以 24.x / ABI 137 为例):

# 下载
curl -L -o bsq.tar.gz "https://github.com/WiseLibs/better-sqlite3/releases/download/v12.5.0/better-sqlite3-v12.5.0-node-v137-win32-x64.tar.gz"
# 解压后覆盖(先备份原文件)
# 目标:node_modules\.pnpm\better-sqlite3@<ver>\node_modules\better-sqlite3\build\Release\better_sqlite3.node

验证:node -p "process.versions.modules" 输出的数字,必须与二进制包名里的 node-vXXX 一致。

2.3 坑之二:系统 PATH 可能被写成 REG_SZ

如果 cmd 里报:

'chcp' 不是内部或外部命令
'taskkill' 不是内部或外部命令

不是脚本问题,而是 HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment 的 Path 值类型被存成了 REG_SZ(应为 REG_EXPAND_SZ),导致 %SystemRoot%\system32 不会展开, System32 实际不在 PATH 中。后果是所有系统命令(ping、ipconfig、where、taskkill)都失效。

检查(PowerShell):

$k = Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'
(Get-ItemProperty $k.PSPath).Path
$k.GetValueKind('Path')      # 期望 ExpandString

修复(管理员权限):

# 备份
$v = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment').Path
$v | Out-File "$env:USERPROFILE\Desktop\Path-backup.txt" -Encoding utf8
# 改类型:值内容不变,仅改类型
$k = Get-Item 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'
[Microsoft.Win32.Registry]::LocalMachine.OpenSubKey(
  'SYSTEM\CurrentControlSet\Control\Session Manager\Environment', $true
).SetValue('Path', $v, [Microsoft.Win32.RegistryValueKind]::ExpandString)

改完必须重启 Agents 客户端 / 资源管理器或注销,新进程才会读到展开后的 PATH。 在此之前,可在启动脚本里临时补偿: bat set "PATH=%SystemRoot%\System32;%SystemRoot%;%SystemRoot%\System32\Wbem;%PATH%"

2.4 目录与文件清单

WebAI2API/
├── supervisor.js              # 看门狗入口
├── package.json
├── scripts/
│   ├── init.js                # 初始化(依赖、浏览器、指纹)
│   ├── start-all.js           # 一键启动器(本教程新增)
│   ├── stop-local.js          # 优雅停止(本教程新增)
│   └── check-port.js          # 端口预检(本教程新增)
├── src/
│   ├── server/                # HTTP、队列、响应
│   ├── backend/
│   │   ├── adapter/           # 20 个站点适配器
│   │   └── engine/            # 浏览器引擎
│   └── config/
├── data/
│   ├── config.yaml            # 主配置
│   ├── camoufoxUserData/      # 浏览器 profile(登录态在这里)
│   ├── logs/system.log        # 运行日志
│   └── history/history.db     # 请求历史
├── 启动服务.bat
├── 停止服务.bat
└── 登录ChatSEU.bat

3. 部署步骤

3.1 安装依赖

下面示例目录为 C:\WebAI2API,请换成你的实际部署路径。

cd "C:\WebAI2API"                        # 换成你的实际部署路径
npm install

安装后检查原生模块是否匹配:

node -p "process.versions.modules"
node -e "const D=require('better-sqlite3');new D(':memory:');console.log('sqlite OK')"

第二条报 ABI 错误 → 回到 2.2 处理。

3.2 配置

编辑 data/config.yaml,重点关注四块:

logLevel: info

server:
  port: 3000
  auth: sk-xxxxxxxx          # API 密钥,至少 10 位;API 与 WebUI 都用它
  keepalive:
    mode: "content"          # 见 9.4,客户端会超时时必须用 content

backend:
  pool:
    strategy: round-robin
    waitTimeout: 120000      # 单次生成等待上限(ChatSEU 建议 ≥120s)
    instances:
      - name: default
        workers:
          - adapter: chatseu_text
            entryUrl: https://chatseu.seu.edu.cn/chat

改配置后必须重启服务才生效(无热加载)。

生成密钥:

node scripts/genkey.js

3.3 启动

两种方式,效果相同:

  • 双击 启动服务.bat(推荐,窗口留存日志)
  • 命令行 node supervisor.js

正常日志应出现:

[看门狗] 主进程已启动
[服务器] 自检通过
[注册表] 适配器加载完成,共 20 个可用
[工作池] 工作池初始化完成,共 1 个 Worker 就绪 (1 个浏览器实例)
[服务器] HTTP 服务器已启动,端口: 3000
[服务器] 运行模式: Supervisor 托管
[服务器] 流式心跳模式: content

没有「进入安全模式」字样,才算健康。

3.4 验证

curl -s http://localhost:3000/v1/models -H "Authorization: Bearer sk-xxxxxxxx"

期望包含 chatseu 与 chatseu_text/chatseu(同一适配器的两种暴露形式)。

再测一次生成(非流式):

curl -s http://localhost:3000/v1/chat/completions `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer sk-xxxxxxxx" `
  -d "{\"model\":\"chatseu\",\"messages\":[{\"role\":\"user\",\"content\":\"回复两个字:可用\"}],\"stream\":false}"

返回 "content":"可用" 即打通。

3.5 调用 API 与客户端配置

这一节解决「拿到地址和密钥之后,客户端里到底填什么、怎么调」。

3.5.1 三个必填项

配置项 填什么 说明
Base URL / 接口地址 http://127.0.0.1:3000/v1 必须带 /v1;少数客户端只让你填到 http://127.0.0.1:3000,它会自动补 /v1
API Key / Token data/config.yaml 里的 server.auth 以 Bearer 形式发送;缺失或错误一律 401
Model / 模型名 chatseu 或 chatseu_text/chatseu 必须精确匹配,先用 /v1/models 查

只在本机使用就填 127.0.0.1。不要为了「让别的设备也能用」改成 0.0.0.0 或做端口映射——见开头安全红线。

3.5.2 常见客户端怎么填

所有「OpenAI 兼容」客户端都一样,只是字段名不同:

客户端里的字段 值
API Base / Base URL / 接口地址 / Endpoint http://127.0.0.1:3000/v1
API Key / Token / 密钥 你的 server.auth
Model / 模型(可自定义填写) chatseu
流式输出 / Stream 建议开启(长回答不走流式容易超时)
上下文 / 历史消息 保持默认,客户端会按 messages 数组传过来
温度 / 最大 tokens / top_p 随便填,服务端会忽略(见 3.5.5)

模型下拉框里如果同时出现 chatseu 和 chatseu_text/chatseu,两者等价,选任意一个。

3.5.3 三种直接调用方式

方式一:cmd 的 curl(Windows)

curl http://127.0.0.1:3000/v1/chat/completions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer sk-your-key" ^
  -d "{\"model\":\"chatseu\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}],\"stream\":false}"

方式二:PowerShell

$body = @{
    model    = "chatseu"
    messages = @(@{ role = "user"; content = "你好" })
    stream   = $false
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "http://127.0.0.1:3000/v1/chat/completions" -Method Post `
  -ContentType "application/json" `
  -Headers @{ Authorization = "Bearer sk-your-key" } `
  -Body $body

方式三:Python(官方 openai SDK)

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:3000/v1",   # 注意带 /v1
    api_key="sk-your-key",
)

resp = client.chat.completions.create(
    model="chatseu",
    messages=[{"role": "user", "content": "你好"}],
)

print(resp.choices[0].message.content)

流式版本:

stream = client.chat.completions.create(
    model="chatseu",
    messages=[{"role": "user", "content": "用三句话介绍东南大学"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

方式四:Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://127.0.0.1:3000/v1',
  apiKey: 'sk-your-key',
});

const res = await client.chat.completions.create({
  model: 'chatseu',
  messages: [{ role: 'user', content: '你好' }],
  stream: true,
});

for await (const chunk of res) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}

用 SDK 时把密钥放到环境变量 OPENAI_API_KEY,代码里不要硬编码,避免误提交。

3.5.4 多轮对话怎么写

服务端会把 messages 拼成「虚拟上下文」,规则是:

system(可选) + 历史(user/assistant 交替) + 最后一条 user

因此:

  • 正常传数组就行:客户端会把历史一起发过来,服务端自动拼
  • 最后一条必须是 user:它才是「当前问题」,前面的都算历史
  • 不要把上下文塞进一条 user 消息:那会变成字面文本,模型会把它当资料而不是对话
{
  "model": "chatseu",
  "messages": [
    { "role": "system", "content": "你是一位严谨的中文技术助理" },
    { "role": "user", "content": "什么是 SSE?" },
    { "role": "assistant", "content": "SSE 是服务端单向推送事件流的技术……" },
    { "role": "user", "content": "它和 WebSocket 有什么区别?" }
  ],
  "stream": true
}

历史越长,最终 prompt 越大,网页端响应也越慢。建议只保留最近 6~10 轮。

3.5.5 参数支持情况

本网关只把请求转成「网页操作」,因此只认下面几个字段:

参数 支持 说明
model ✅ 必须与 /v1/models 里的 id 完全一致
messages ✅ 必须含至少一条 role: user
stream ✅ true 返回 SSE 流;false 一次性返回
reasoning ✅ true 时若模型支持,会额外返回 reasoning_content
temperature、top_p、max_tokens、stop、n、presence_penalty、frequency_penalty、user、tools ❌ 会被忽略,不报错。网页端无法控制采样参数,别指望靠它们调风格

所以:客户端里那些「温度」「最大长度」滑块可以随便设,不影响结果; 想控制输出长短,只能在 prompt 里写清楚要求(例如「控制在 200 字以内」)。

3.5.6 并发、队列与超时

配置位置:data/config.yaml

queue:
  queueBuffer: 2            # 队列缓冲,默认 2;设为 0 表示不限制

backend:
  pool:
    workers:
      - adapter: chatseu_text
        entryUrl: https://chatseu.seu.edu.cn/chat

规则:

概念 值 说明
maxConcurrent = workers 数量(当前 1) 自动计算,不用手填
队列容量 maxConcurrent + queueBuffer 当前即 1 + 2 = 3
非流式请求 队列满 → 直接 429 提示改用流式
流式请求 排队等待,不拒绝 等待期间每 3 秒收到心跳空包

实践建议:

  • 客户端一律用流式:既不会 429,也不容易触发客户端超时
  • 单 worker 时不要并发调用(第 2 个请求会排队,总耗时翻倍)
  • ChatSEU 单次生成 30~90 秒很常见,客户端超时建议设到 180 秒以上

3.5.7 错误码对照表

HTTP code 含义 怎么处理
401 UNAUTHORIZED 密钥缺失或错误 核对 server.auth,注意 Bearer 前缀
400 NO_MESSAGES 请求体缺 messages 补上数组
400 NO_USER_MESSAGES 没有 role: user 的消息 至少放一条用户消息
400 INVALID_MODEL 模型名不对 先 GET /v1/models 查准确 id
400 IMAGE_FORBIDDEN 该模型不接受图片 chatseu 是纯文本模型
403 RECAPTCHA 触发人机验证 降低频率;必要时重新登录
429 SERVER_BUSY 队列已满(仅非流式) 改 stream: true 或稍后重试
500 INTERNAL_ERROR 服务内部异常 看 data/logs/system.log
502 GENERATION_FAILED 生成失败 常见原因:登录态失效、页面改版、网络问题(见 9.7)
503 BROWSER_NOT_INITIALIZED 浏览器未就绪 服务刚启动,或工作池初始化失败(见 9.6)

错误响应体是 OpenAI 格式:

{
  "error": {
    "message": "未登录:请先用登录模式完成东南大学统一身份认证",
    "type": "server_error",
    "code": "GENERATION_FAILED"
  }
}

遇到 502 时先看 message:写「未登录」就去第 4 章重新登录; 写「未找到输入框」多半是页面改版,按第 6 章更新选择器。

3.5.8 其他可用接口

接口 用途
GET /v1/models 查询可用模型(客户端配置前先看这里)
GET /v1/cookies?name=<worker名>&domain=<域名> 读取当前浏览器 cookie,用于排查登录态
GET / WebUI:查看日志、队列、历史、修改配置
/admin/* WebUI 内部使用的管理接口(状态、重启、统计、历史)

查询 cookie 示例:

$key = "sk-your-key"
Invoke-RestMethod "http://127.0.0.1:3000/v1/cookies?name=chatseu&domain=chatseu.seu.edu.cn" `
  -Headers @{ Authorization = "Bearer $key" }

⚠️ 这个接口会返回真实登录凭据。只在本机调试时用,截图/分享前务必打码, 更不要把它接到任何公网服务上。

3.5.9 调用侧的三条纪律

  1. 地址恒为 127.0.0.1:不要改 0.0.0.0、不做端口映射/内网穿透,见开头安全红线。
  2. 密钥走环境变量:OPENAI_API_KEY=sk-...,不要写进代码或提交到仓库。
  3. 控制频率:单账号、低频、串行。这是校园共用服务,不是私人算力。

4. 登录 ChatSEU

4.1 为什么需要「登录模式」

ChatSEU 用东南大学统一身份认证(CAS),必须人工完成一次登录。 登录态存在浏览器 profile(data/camoufoxUserData)里,之后可复用。

关键约束:

  • 登录模式与常驻服务不能同时运行:两者抢 3000 端口,且共用同一个 profile, Firefox 的 profile 同一时刻只能被一个实例独占,第二个实例会立刻退出(exitCode=0)。
  • 登录时必须用有头浏览器(能看见窗口),否则没法输账号密码。

4.2 登录流程(推荐用一键脚本)

node scripts/start-all.js --force-login

它会:

  1. 停掉所有残留实例(含浏览器)
  2. 以 -login=chatseu 拉起有头浏览器
  3. 轮询 cookie,检测到登录凭据变化后自动切回常驻模式
  4. 自测一次模型,打印「服务已就绪」

手动分步版本:

# 1) 先停服务
node scripts/stop-local.js
# 2) 登录模式
node supervisor.js -login=chatseu
# 3) 浏览器里完成认证后,Ctrl+C 退出
# 4) 再起常驻
node supervisor.js

4.3 登录态存储与判断

项 值
profile 目录 data/camoufoxUserData
cookie 库 data/camoufoxUserData/cookies.sqlite
关键 cookie auth.seu.edu.cn 的 TGT、chatseu.seu.edu.cn 的会话 cookie

判断是否登录:读 moz_cookies 表(浏览器运行时可用「复制 sqlite + wal 再只读打开」的方式绕过文件锁)。

// 复制 cookies.sqlite / -wal / -shm 到临时目录,再只读查询
select host, name, value, expiry from moz_cookies;

注意:TGT 存在 ≠ 会话有效。服务端可能已失效,此时请求返回 未登录:请先用登录模式…。所以最终判据是真实调用一次模型,而不是只看 cookie。

5. 刮削 ChatSEU:抓包与协议分析

5.1 抓什么

一个网页版 AI,抓包目标只有三类:

目标 作用
输入框选择器 让脚本能找到并输入内容
发送方式 回车 / 点按钮 / 调接口
回复通道 回答从哪个响应返回(XHR / SSE / WebSocket / DOM 渲染)

ChatSEU 的关键结论:正文不在 POST 上,走独立 SSE 通道。

5.2 找到回复通道

观察页面行为:

  1. 发送消息后,DevTools → Network → Filter Fetch/XHR
  2. 会看到两条请求: - POST /api/chat/streamchat → 仅返回 ack: json {"code":0,"response":"1bc389eb-7e72-4f7a-a995-7db8dbe350c0"} - GET /api/chat/streamchat?messageId=<uuid> → text/event-stream,真正的 token 流

这是一个常见模式:POST 换会话 ID,GET 拿流。 适配器必须监听第二条,而不是从 POST 响应里找内容。

5.3 SSE 报文结构

实际抓到的片段(已脱敏):

id:1bc389eb-7e72-4f7a-a995-7db8dbe350c0
event:metadata
data:{"now":1794375410941,"exists":false,"fileResponseList":[],"rounds":1}

id:1bc389eb-7e72-4f7a-a995-7db8dbe350c0
data:1
retry:3000

id:1bc389eb-7e72-4f7a-a995-7db8dbe350c0
data:加
retry:3000

id:1bc389eb-7e72-4f7a-a995-7db8dbe350c0
data:[DONE]
retry:3000

要点:

  • 纯增量:每帧只带新 token,不会重复推送全文(这决定了拼接逻辑是「直接相连」)
  • event:metadata 是元信息包,必须跳过,不能进正文
  • data: 里以 { 或 [ 开头的可能是 JSON 控制包,要尝试解析并跳过; 但也要小心「正文恰好以 { 开头」的情况(解析失败就当文本处理)
  • 空行是事件块分隔符,event: 字段只对当前块有效,处理时必须重置
  • [DONE] 表示结束

5.4 空白占位符还原

站点把换行、空格、Tab 编码成了占位符,直接拼接会丢格式:

function normalizeText(text) {
    return text
        .replace(/\[line\]/gi, '\n')
        .replace(/\[space\]/gi, ' ')
        .replace(/\[tab\]/gi, '\t');
}

5.5 通用抓包方法(换站点时照做)

  1. 先登录,再抓包——未登录时看到的响应不是真实的(会被重定向到认证页)
  2. 在页面 Console 里挂一个全局监听,比肉眼快:
// 在 DevTools Console 执行,然后发一条消息
const origOpen = XMLHttpRequest.prototype.open;
XMLHttpRequest.prototype.open = function (m, u) {
    if (/stream|chat|complet|message/i.test(u)) console.log('[XHR]', m, u);
    return origOpen.apply(this, arguments);
};
window.addEventListener('message', e => console.log('[MSG]', e.data));
  1. 用 Playwright 侧监听(更贴近适配器运行时):
page.on('response', async (res) => {
    const ct = (res.headers()['content-type'] || '').toLowerCase();
    if (ct.includes('event-stream') || /stream/i.test(res.url())) {
        console.log(res.request().method(), res.url());
    }
});
  1. 找到「首帧时间」与「总耗时」——这决定 waitTimeout 与客户端超时策略(见 9.5)。

5.6 常见误区

误区 说明
从 POST 响应取正文 多数站点 POST 只回 ack/ID
用 DOM 抓回答 流式渲染时容易抓到"中间态",且易被改版打断
忽略 event: 块作用域 上一块的 metadata 会污染下一块,导致整段回答被丢弃
忘了占位符还原 输出全部挤成一行
只测短问题 短回答往往单帧返回,掩盖了拼接 bug

6. 开发适配器

6.1 文件位置与最小结构

新增站点 = 在 src/backend/adapter/ 下加一个 .js 文件(ESM),导出 manifest 与 generate。 参考实现:src/backend/adapter/chatseu_text.js(约 240 行)。

import { sleep, humanType, safeClick } from '../engine/utils.js';
import { normalizePageError, waitForInput, gotoWithCheck } from '../utils/index.js';
import { logger } from '../../utils/logger.js';

const TARGET_URL = 'https://chatseu.seu.edu.cn/chat';

async function generate(context, prompt, imgPaths, modelId, meta = {}) { /* ... */ }

export const manifest = {
    id: 'chatseu_text',
    displayName: 'ChatSEU (东南大学校园 AI)',
    description: '通过东南大学 ChatSEU 对话页生成文本。需要先完成统一身份认证。',
    configSchema: [],
    getTargetUrl(config, workerConfig) {
        return workerConfig?.entryUrl || TARGET_URL;
    },
    models: [
        { id: 'chatseu', imagePolicy: 'forbidden', type: 'text' }
    ],
    navigationHandlers: [],
    generate
};

6.2 manifest 字段说明

字段 作用 注意
id 适配器唯一标识 决定模型别名前缀:<id>/<model>
displayName / description WebUI 展示 —
configSchema 该适配器特有的配置项 无则空数组
getTargetUrl(config, worker) 入口地址 允许 worker 的 entryUrl 覆盖
models 暴露的模型列表 type: 'text' 才会走文本解析分支
imagePolicy forbidden / allowed 决定是否接受图片输入
navigationHandlers 站点特定导航处理 多数站点为空
generate 核心函数 见 6.3

type: 'text' 非常关键:否则 parse.js 会走「图像生成(仅取最后一条)」分支, 你的多轮上下文会被丢掉。

6.3 generate 的标准实现顺序

async function generate(context, prompt, imgPaths, modelId, meta = {}) {
    const { page, config } = context;
    const waitTimeout = config?.backend?.pool?.waitTimeout ?? 120000;
    try {
        // 1) 打开入口(超时兜底:load 不触发时退回 domcontentloaded)
        try {
            await gotoWithCheck(page, TARGET_URL);
        } catch (err) {
            await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 45000 });
        }
        await sleep(800, 1400);

        // 2) 登录态检查(被重定向到认证域就直接返回可执行提示)
        if (page.url().includes('auth.seu.edu.cn')) {
            return { error: '未登录:请先用登录模式完成统一身份认证' };
        }

        // 3) 找输入框
        const input = await findInput(page);
        if (!input) return { error: '未找到输入框:页面可能改版,或登录态已失效' };
        await waitForInput(page, input, { click: true });

        // 4) 先挂监听,再发送(否则流已经开始了)
        const responsePromise = page.waitForResponse(isTargetStream, { timeout: waitTimeout });

        // 5) 输入 + 回车
        await safeClick(page, input, { bias: 'input' });
        await humanType(page, input, prompt);
        await sleep(300, 600);
        await page.keyboard.press('Enter');

        // 6) 等流结束,拿完整报文
        const response = await responsePromise;
        const raw = await response.text();
        const text = extractStreamText(raw);

        if (!text.trim()) return { error: '回复内容为空' };
        return { text: text.trim() };
    } catch (err) {
        const pageError = normalizePageError(err, meta);
        if (pageError) return pageError;
        return { error: err.message };
    }
}

三个顺序不能错:

  1. 先挂 waitForResponse,再回车 —— 反了就永远等不到响应
  2. response.text() 会等到流结束 —— 天然拿到完整报文,无需自己拼帧
  3. 错误必须 return { error } 而不是 throw —— 让上层能按 retryable 决定 502/503

6.4 输入框定位

用「候选选择器 + 轮询」比单一定位更抗改版:

const INPUT_SELECTORS = [
    'textarea',
    'div[contenteditable="true"]',
    '.chat-input textarea',
    '[role="textbox"]'
];

async function findInput(page, timeout = 20000) {
    const deadline = Date.now() + timeout;
    while (Date.now() < deadline) {
        for (const selector of INPUT_SELECTORS) {
            try {
                const locator = page.locator(selector).first();
                if (await locator.count() > 0 && await locator.isVisible()) return locator;
            } catch { /* 换下一个 */ }
        }
        await sleep(300, 500);
    }
    return null;
}

经验:textarea 优先级最高;contenteditable 站点注意回车可能触发换行而非发送。

6.5 响应监听与解析

匹配条件要同时兼容「URL 特征」和「Content-Type」:

const responsePromise = page.waitForResponse((response) => {
    const request = response.request();
    if (request.method() !== 'GET') return false;

    const url = response.url();
    if (url.includes('/api/chat/streamchat') && /messageId=/.test(url)) return true;

    const contentType = (response.headers()['content-type'] || '').toLowerCase();
    return contentType.includes('event-stream');
}, { timeout: waitTimeout });

解析(关键:按事件块处理,event 每块重置):

function extractStreamText(raw) {
    const chunks = [];
    let eventName = '';

    for (const line of raw.split(/\r?\n/)) {
        if (line === '') { eventName = ''; continue; }          // 块结束
        if (line.startsWith('event:')) { eventName = line.slice(6).trim(); continue; }
        if (line.startsWith('id:') || line.startsWith('retry:') || line.startsWith(':')) continue;
        if (!line.startsWith('data:')) continue;

        const payload = line.slice(5).trim();
        if (!payload) continue;
        if (payload === '[DONE]') break;
        if (eventName === 'metadata') continue;                  // 元信息包

        if (payload.startsWith('{') || payload.startsWith('[')) {
            try {
                const parsed = JSON.parse(payload);
                if (parsed && typeof parsed === 'object') continue;  // 控制包
            } catch { /* 以 { 开头的普通文本 */ }
        }
        chunks.push(payload);
    }
    return normalizeText(chunks.join(''));
}

6.6 调试开关(强烈建议保留)

在 generate 里加一段:设置 WA2A_DUMP_SSE=1 时把原始报文落盘。 排查「回答重复 / 截断 / 空白」时,这是唯一的一手证据。

if (process.env.WA2A_DUMP_SSE) {
    const fs = await import('node:fs');
    const path = await import('node:path');
    const dir = path.resolve(process.cwd(), 'data', 'logs');
    fs.mkdirSync(dir, { recursive: true });
    fs.writeFileSync(path.join(dir, `sse-${Date.now()}.txt`), raw, 'utf-8');
}

启用:

$env:WA2A_DUMP_SSE = "1"; node supervisor.js

6.7 注册与模型暴露

适配器放进目录后无需手动注册:启动时扫描 src/backend/adapter/, 日志出现 适配器加载完成,共 N 个可用 即成功。

模型会以两种形式出现在 /v1/models:

  • chatseu(直接模型名)
  • chatseu_text/chatseu(<适配器id>/<模型id>)

客户端填哪个都能用。

6.8 适配器自测清单

检查项 方法
能打开入口 看日志是否出现「打开 XX 对话页」后紧接「输入提示词」
能找到输入框 失败会返回 未找到输入框
能抓到流 日志「等待生成结果」后多久出现「已获取文本内容」
内容完整 用长问题(≥3 句)测,避免短回答掩盖拼接 bug
格式正确 检查换行是否还原(占位符处理)
多轮可用 第二轮带 assistant 历史,确认不串话
异常可读 未登录时返回的 error 必须是可执行提示,而不是 stack

7. 运维脚本与自动化

直接 npm start 有三个问题:不会检查登录态、不会清理残留、崩溃后窗口一关就全没了。 本教程用三个脚本 + 一个启动器解决。

7.1 一键启动器 scripts/start-all.js

核心流程:

1. stopAll()          // IPC STOP + 清理 camoufox(等待 8s 让浏览器把登录态写回 profile)
2. waitPortFree()     // 端口预检,避免 EADDRINUSE
3. readLoginState()   // 读取 cookies.sqlite(复制后只读,绕过文件锁)
4. 有凭据 → 直接起常驻;无凭据 → 进入 loginFlow()
5. loginFlow()        // 有头浏览器 + 轮询 cookie 变化(TGT 或 chatseu 会话 cookie)
6. serveAndVerify()   // 起 supervisor → 等 /v1/models → 真发一次 chat 自测
7. 自测失败 → 重新登录一轮,仍失败则明确报错

两个设计要点:

  • 判据必须是「cookie 值变化」:只看「有没有 TGT」会误判(旧票据仍在,但服务端会话已失效)。
  • 停止时不要立刻 taskkill:先发 STOP,等 8 秒让浏览器落盘 cookie,否则重启后又要重新登录。

7.2 优雅停止 scripts/stop-local.js

1. 连接命名管道 \\.\pipe\webai2api-supervisor,发送 STOP
2. 等待进程退出
3. 若仍有 camoufox 残留,才强制 taskkill

命名管道是 supervisor 提供的 IPC 通道,比直接杀进程更干净(能保证子服务正常收尾)。

7.3 端口预检 scripts/check-port.js

const srv = net.createServer();
srv.once('error', () => process.exit(1));       // 被占用
srv.once('listening', () => srv.close(() => process.exit(0)));
srv.listen(3000);

7.4 三个 bat 的分工

脚本 用途 内部命令
启动服务.bat 日常启动(自动判断登录态) node scripts/start-all.js
登录ChatSEU.bat 强制重新登录 node scripts/start-all.js --force-login
停止服务.bat 停止 + 清理 node scripts/stop-local.js

bat 里必须做的三件事(否则会遇到 9.4 的问题):

@echo off
setlocal
rem 1) 系统 PATH 可能缺 System32(Path 被写成 REG_SZ),本地补偿
set "PATH=%SystemRoot%\System32;%SystemRoot%;%SystemRoot%\System32\Wbem;%PATH%"
cd /d "%~dp0"
rem 2) 固定 Node,避免 PATH 里其他版本导致 ABI 不匹配
set "NODE_EXE=C:\Program Files\nodejs\node.exe"
if not exist "%NODE_EXE%" set "NODE_EXE=node"
rem 3) 静默设置代码页,失败也不报错
chcp 65001 >nul 2>&1
"%NODE_EXE%" scripts\start-all.js
pause >nul

文件必须存成 CRLF + 纯 ASCII。UTF-8 中文 + LF 换行会让 cmd 解析错乱, 出现 '~dp0"' 不是内部或外部命令 这类诡异报错。

7.5 脚本内部也不要依赖 PATH

start-all.js / stop-local.js 里调用系统命令时用绝对路径:

const SYS32 = path.join(process.env.SystemRoot || 'C:\\Windows', 'System32');
execFileSync(path.join(SYS32, 'taskkill.exe'), ['/F', '/IM', 'camoufox.exe', '/T'], { stdio: 'ignore' });
execFileSync(path.join(SYS32, 'tasklist.exe'), ['/FI', 'IMAGENAME eq camoufox.exe', '/NH'], { encoding: 'utf-8' });

8. 接入 Agents 客户端:把生成能力变成一句话

目标:在 Agents 客户端里说「用 chatseu 生成 XX 页面,保存到 Y」,自动完成生成 + 落盘 + 预览。

8.1 技能目录结构

<Agents数据目录>\skills\chatseu-codegen\
├── SKILL.md                      # 触发条件 + 执行流程
├── SKILL.reactive.json           # 关键词索引(中英文)
├── scripts\generate_page.mjs     # 生成 + 落盘脚本
└── logs\run-*.json               # 每次执行留痕(自动生成)

<Agents数据目录> 请替换为本机 Agents 客户端的技能目录(例如 %USERPROFILE%\.agents)。

SKILL.md 需要 YAML 头:

---
name: chatseu-codegen
description: 当用户要求用 chatseu 生成网页或代码并保存到指定路径时使用……
---

SKILL.reactive.json:

{
  "description": "Generate a single-file HTML page with the local ChatSEU model and save it to a path",
  "keywords": ["chatseu generate page", "save generated code"],
  "keywords_zh": ["chatseu生成代码", "生成网页并保存", "代码落地"]
}

8.2 生成脚本的职责

"C:\Program Files\nodejs\node.exe" "<Agents数据目录>\skills\chatseu-codegen\scripts\generate_page.mjs" --prompt "<需求>" --out "<绝对路径>.html" --overwrite

脚本做四件事:

  1. 探测 /v1/models,服务没起就直接给可执行提示
  2. 调 /v1/chat/completions(带「只输出单文件 HTML」的 system 约束)
  3. 从回复中提取代码块,校验 <html / </html>
  4. 写文件 + 输出 JSON(path / bytes / previewUrl)

返回示例:

{
  "ok": true,
  "path": "C:\\Users\\suda\\Desktop\\todo.html",
  "bytes": 12512,
  "chars": 12434,
  "model": "chatseu",
  "durationMs": 50822,
  "previewUrl": "file:///C:/Users/suda/Desktop/todo.html"
}

8.3 三条工程经验

  1. 命令必须写成一行:PowerShell 不支持 \ 续行,多行会直接语法报错。
  2. 需求用 --prompt-file 传:中文引号在命令行里容易被吞掉。
  3. 每次执行写日志:logs/run-*.json 记录参数与结果,失败时可直接定位,不靠猜。

9. 实战排错手册

这一节全部来自真实故障,按「现象 → 判断 → 处理」组织。

9.1 NODE_MODULE_VERSION 127 … requires 137

现象

[WARN] [服务器] 历史记录数据库初始化失败 | error=was compiled against a different Node.js version
       NODE_MODULE_VERSION 127. This version of Node.js requires NODE_MODULE_VERSION 137
[ERRO] [工作池] [chatseu] 初始化失败,跳过该 Worker
[ERRO] [服务器] 工作池初始化失败 | error=所有 Worker 初始化都失败了
[WARN] [服务器] 进入安全模式

判断:better-sqlite3 二进制 ABI 与当前 Node 不一致。

处理:按 2.2 下载对应 ABI 的预编译二进制并覆盖;或换回匹配的 Node。 两个位置都要覆盖(pnpm 下真实文件在 .pnpm 里,node_modules/better-sqlite3 可能是链接)。

验证:

node -e "const D=require('better-sqlite3');new D(':memory:');console.log('ok')"

9.2 EADDRINUSE: address already in use :::3000 / \\.\pipe\webai2api-supervisor

现象:启动后疯狂刷重启,日志里端口和管道都冲突。

判断:已有实例在跑(常见于重复双击 bat,或登录模式和常驻模式同时开)。

处理:

node scripts/stop-local.js     # 先停
node scripts/start-all.js      # 再起(内部有端口预检)

预防:bat 启动前跑 check-port.js;登录脚本开头先 stop-local.js --quiet。

9.3 Target page, context or browser has been closed

现象:浏览器刚起来就 exitCode=0 退出,随后 Worker 初始化失败。

<launched> pid=22236
[pid=22236] <process did exit: exitCode=0, signal=null>
browserType.launchPersistentContext: Target page, context or browser has been closed

判断:profile 被占用。Firefox 的 user-data-dir 同一时刻只能被一个实例独占。

处理:确认没有第二个实例(登录模式 + 常驻模式同时跑是最常见原因), stop-local.js 清理干净后只保留一个。

预防:登录脚本自动先停服务;不要手动并发启动。

9.4 'chcp' 不是内部或外部命令

现象:bat 第一行就报错,但后续功能正常;taskkill 也失效导致浏览器残留。

判断:系统 PATH 缺 C:\Windows\System32——通常是 Path 注册表值被写成 REG_SZ(见 2.3)。

处理:

  • 立即:bat 内补 PATH(7.4),脚本内用绝对路径(7.5)
  • 根治:把 Path 类型改回 REG_EXPAND_SZ,重启 Agents 客户端/资源管理器

9.5 回答重复:「1加1等于2。 1加1等于2。」

现象:客户端里同一句话出现两遍。

排查顺序(重要:先证明服务端,再看客户端)

  1. 看上游 SSE 原始报文:WA2A_DUMP_SSE=1,确认是纯增量(无全文重发)
  2. 看 history.db 的 response_text:是否已经是两份 sql select id, created_at, response_text from requests order by created_at desc limit 5;
  3. 看服务日志是否同一问题出现两次请求(不同 requestId、间隔 10~30 秒)

结论与处理:

  • 服务端记录是单份 → 客户端侧发生「超时重试 + 两次响应拼接」
  • 根因通常是首字节慢:ChatSEU 单次 10~60 秒,客户端等不到数据就重试
  • 处理:把心跳从注释改为 JSON 空包,让客户端能重置超时
server:
  keepalive:
    mode: "content"     # 每 3 秒推一个空 delta;comment 模式部分客户端不认

验证:流式请求应看到多个 data: 帧(空 delta + 内容),而不是 :keepalive 注释。

9.6 安全模式:WebUI 能开,API 却不可用

现象

[WARN] [服务器] 进入安全模式:WebUI 和 Admin API 可用,OpenAI API 不可用

判断:工作池初始化失败(所有 worker 都起不来)。安全模式是「降级」,不是正常状态。

排查:向上翻日志找第一条 [ERRO],通常是: - ABI 不匹配(9.1) - profile 被占用(9.3) - 登录模式未启用但有头启动失败

9.7 未登录 / 未找到输入框 / 回复内容为空

日志 含义 处理
当前会话未登录统一身份认证 被重定向到 auth.seu.edu.cn 重新登录
未找到输入框:页面可能改版,或登录态已失效 页面结构变了,或登录态半失效 先重登;仍失败则更新选择器
回复内容为空 抓到流但没有有效 token 开 dump 看报文,确认是否只有 metadata
页面加载失败: page.goto: NS_ERROR_FAILURE 网络/证书/代理问题 换网、检查代理、重试

9.8 生成很慢或超时

  • ChatSEU 长回答(代码类)可能 60~90 秒,属正常
  • waitTimeout 建议 ≥ 120000;客户端超时也要同步放宽
  • 队列是串行(maxConcurrent=1),并发请求会排队,日志里 remaining 可看积压

9.9 浏览器残留

现象:服务停了但 camoufox.exe 还在,占内存、占 profile。

处理:

# 正常路径
node scripts/stop-local.js
# 极端情况
"C:\Windows\System32\taskkill.exe" /F /IM camoufox.exe /T

不要频繁强杀:浏览器来不及把 cookie 写回 profile,下次启动可能又要重新登录。


10. 日志、历史与监控

10.1 运行日志 data/logs/system.log

关键行速查:

日志 说明
自检通过 配置/依赖 OK
适配器加载完成,共 N 个可用 适配器扫描结果
工作池初始化完成,共 1 个 Worker 就绪 浏览器可用
HTTP 服务器已启动,端口: 3000 服务就绪
流式心跳模式: content 心跳配置
请求入队 … remaining=N 队列积压
已获取文本内容 (N 字符) 上游返回长度,异常短/长要警惕
进入安全模式 故障态

10.2 历史库 data/history/history.db

表 requests 主要字段:

字段 说明
id 请求 ID(与日志中的 requestId 对应)
created_at 毫秒时间戳
model_id / model_name 模型
prompt 最终拼好的完整 prompt(含系统指令与历史)
response_text 服务端最终返回的文本(排查重复的第一现场)
status success / failed / pending
error_message 失败原因
duration_ms 耗时
is_streaming 是否流式

查询最近 10 次:

select datetime(created_at/1000,'unixepoch','localtime') as t,
       id, model_name, status, length(response_text) as len, duration_ms
from requests order by created_at desc limit 10;

浏览器运行时库文件被占用,可复制 history.db + -wal + -shm 后再只读打开。

10.3 健康检查脚本(可选)

# 一次性检查:端口 + 模型列表 + 一次真实对话
$key = "sk-xxxx"
(Invoke-RestMethod http://localhost:3000/v1/models -Headers @{Authorization="Bearer $key"}).data.id

11. 附录:命令速查

# ---------- 部署 ----------
cd "C:\WebAI2API"
npm install
node -p "process.versions.modules"          # 期望 137(Node 24)
node scripts/genkey.js                      # 生成 API 密钥

# ---------- 启动 / 停止 ----------
node supervisor.js                          # 直接启动
node scripts/start-all.js                   # 一键启动(自动判断登录态)
node scripts/start-all.js --force-login     # 强制重新登录
node scripts/stop-local.js                  # 优雅停止
node scripts/check-port.js                  # 端口检查(exit 0 可用 / 1 被占用)

# ---------- 验证 ----------
curl -s http://localhost:3000/v1/models -H "Authorization: Bearer sk-xxxx"
curl -s http://localhost:3000/v1/chat/completions ^
  -H "Content-Type: application/json" -H "Authorization: Bearer sk-xxxx" ^
  -d "{\"model\":\"chatseu\",\"messages\":[{\"role\":\"user\",\"content\":\"回复:可用\"}],\"stream\":false}"

# ---------- 调试 ----------
$env:WA2A_DUMP_SSE = "1"                    # 抓原始 SSE 到 data/logs/sse-*.txt
Get-Content data\logs\system.log -Tail 50   # 看最近日志

# ---------- 清理 ----------
node scripts/stop-local.js
"C:\Windows\System32\taskkill.exe" /F /IM camoufox.exe /T

# ---------- 技能 ----------
"C:\Program Files\nodejs\node.exe" "<Agents数据目录>\skills\chatseu-codegen\scripts\generate_page.mjs" --prompt "生成一个番茄钟页面" --out "C:\Users\suda\Desktop\pomodoro.html" --overwrite

结语

这套方案的本质是「用浏览器自动化 + 协议解析,把没有 API 的站点变成标准 API」。 可复用的部分远不止 ChatSEU:

  • 抓包方法(5.5)适用于任何站点
  • 适配器骨架(6.1~6.5)只改三处:入口 URL、输入框选择器、流匹配条件
  • 排错思路(9 章)对所有适配器通用:先证明服务端,再怀疑客户端

新增站点的最短路径:

  1. 登录 → 抓包,确认回复走哪个响应
  2. 复制 chatseu_text.js,改 TARGET_URL / 选择器 / 解析
  3. 起服务,用长问题测一次
  4. 看 system.log 与 data/logs/sse-*.txt 校准

维护提示:站点改版后,最先坏的通常是输入框选择器和流 URL 特征。 把这两处写成配置项/常量,能让下次修复控制在 5 分钟以内。