笔记 · 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. 原理与架构
- 2. 环境准备(两个必查的坑)
- 3. 部署步骤
- 3.5 调用 API 与客户端配置
- 4. 登录 ChatSEU
- 5. 刮削 ChatSEU:抓包与协议分析
- 6. 开发适配器
- 7. 运维脚本与自动化
- 8. 接入 Agents 客户端:把生成能力变成一句话
- 9. 实战排错手册
- 10. 日志、历史与监控
- 11. 附录:命令速查
0. 你能得到什么
完成全部步骤后:
- 本地跑起一个 OpenAI 兼容网关:
http://localhost:3000/v1 - 通过它调用 东南大学 ChatSEU(浏览器自动化,无官方 API 也能用)
- 自己新增站点适配器,把任意网页版 AI 接进来
- 在 Agents 客户端 / 任意 OpenAI 客户端里直接选模型使用
- 具备一套排错能力:能定位 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 调用侧的三条纪律
- 地址恒为
127.0.0.1:不要改0.0.0.0、不做端口映射/内网穿透,见开头安全红线。 - 密钥走环境变量:
OPENAI_API_KEY=sk-...,不要写进代码或提交到仓库。 - 控制频率:单账号、低频、串行。这是校园共用服务,不是私人算力。
4. 登录 ChatSEU
4.1 为什么需要「登录模式」
ChatSEU 用东南大学统一身份认证(CAS),必须人工完成一次登录。
登录态存在浏览器 profile(data/camoufoxUserData)里,之后可复用。
关键约束:
- 登录模式与常驻服务不能同时运行:两者抢 3000 端口,且共用同一个 profile,
Firefox 的 profile 同一时刻只能被一个实例独占,第二个实例会立刻退出(
exitCode=0)。 - 登录时必须用有头浏览器(能看见窗口),否则没法输账号密码。
4.2 登录流程(推荐用一键脚本)
node scripts/start-all.js --force-login
它会:
- 停掉所有残留实例(含浏览器)
- 以
-login=chatseu拉起有头浏览器 - 轮询 cookie,检测到登录凭据变化后自动切回常驻模式
- 自测一次模型,打印「服务已就绪」
手动分步版本:
# 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 找到回复通道
观察页面行为:
- 发送消息后,DevTools → Network → Filter
Fetch/XHR - 会看到两条请求:
-
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 通用抓包方法(换站点时照做)
- 先登录,再抓包——未登录时看到的响应不是真实的(会被重定向到认证页)
- 在页面 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));
- 用 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());
}
});
- 找到「首帧时间」与「总耗时」——这决定
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 };
}
}
三个顺序不能错:
- 先挂
waitForResponse,再回车 —— 反了就永远等不到响应 response.text()会等到流结束 —— 天然拿到完整报文,无需自己拼帧- 错误必须
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
脚本做四件事:
- 探测
/v1/models,服务没起就直接给可执行提示 - 调
/v1/chat/completions(带「只输出单文件 HTML」的 system 约束) - 从回复中提取代码块,校验
<html/</html> - 写文件 + 输出 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 三条工程经验
- 命令必须写成一行:PowerShell 不支持
\续行,多行会直接语法报错。 - 需求用
--prompt-file传:中文引号在命令行里容易被吞掉。 - 每次执行写日志:
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。」
现象:客户端里同一句话出现两遍。
排查顺序(重要:先证明服务端,再看客户端)
- 看上游 SSE 原始报文:
WA2A_DUMP_SSE=1,确认是纯增量(无全文重发) - 看
history.db的response_text:是否已经是两份sql select id, created_at, response_text from requests order by created_at desc limit 5; - 看服务日志是否同一问题出现两次请求(不同 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 章)对所有适配器通用:先证明服务端,再怀疑客户端
新增站点的最短路径:
- 登录 → 抓包,确认回复走哪个响应
- 复制
chatseu_text.js,改TARGET_URL/ 选择器 / 解析 - 起服务,用长问题测一次
- 看
system.log与data/logs/sse-*.txt校准
维护提示:站点改版后,最先坏的通常是输入框选择器和流 URL 特征。 把这两处写成配置项/常量,能让下次修复控制在 5 分钟以内。