webaiapi 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webaiapi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# webaiapi（命令名：`webapi`）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把国产 AI 聊天网页（目前支持 **ChatGLM / 智谱清言**）包装成 **OpenAI 兼容 API**。
+纯浏览器自动化（Playwright Firefox），**不需要 API Key、不需要逆向签名**——你只要在浏览器里登录一次。
+
+用它可以在任何支持 OpenAI 协议的客户端（CodeBuddy、Trae、Cursor、各类 SDK）里，
+直接使用你的网页端账号额度。
+
+---
+
+## 安装
+
+```bash
+npm i -g webaiapi
+```
+
+安装时会**自动下载 Playwright Firefox**（约 80MB，只需一次）。
+若你的环境禁用了安装脚本（`--ignore-scripts`）或被网络策略拦住，
+手动补一条即可：
+
+```bash
+npx playwright install firefox
+```
+
+然后登录并捕获凭证（会打开可见的浏览器，你手动登录）：
+
+```bash
+webapi login
+```
+
+不加参数会**交互式**让你选平台（`↑/↓` + 回车，或直接敲编号），随后选「添加账号 / 重新登录」。
+想跳过菜单就直接给平台名：`webapi login chatglm`。
+
+> 不确定环境有没有问题？先跑一次自检：
+
+```bash
+webapi doctor
+```
+
+它会检查 Node 版本、Firefox 二进制、凭证、端口，并给出可复制的修复命令。
+
+> **跳过自动下载**：设 `WEBAIAPI_SKIP_BROWSER_INSTALL=1`（或用 Playwright 自己的
+> `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`）。CI 里常用。
+
+## 启动
+
+```bash
+webapi start
+```
+
+服务默认监听 `http://0.0.0.0:8631`，OpenAI 兼容端点在 `/v1`：
+
+```bash
+# 健康检查
+curl -s http://localhost:8631/v1/health
+
+# 对话（非流式）
+curl -s -X POST http://localhost:8631/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"chatglm","messages":[{"role":"user","content":"你好"}]}'
+
+# 流式
+curl -N -X POST http://localhost:8631/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"chatglm","messages":[{"role":"user","content":"你好"}],"stream":true}'
+```
+
+在客户端里配置基址 `http://localhost:8631/v1`，API Key 随便填（未启用校验时），
+模型名填 `chatglm` 或 `mix`。
+
+## 命令
+
+| 命令 | 说明 |
+|---|---|
+| `webapi start` | 启动服务（前台运行，Ctrl-C 退出） |
+| `webapi doctor` | 自检：Node / Firefox / 凭证 / 端口 |
+| `webapi status` | 运行状态：账号、角色、辅助通道、请求池 |
+| `webapi accounts` | 只看账号与角色（判断「多账号有没有生效」的权威视图） |
+| `webapi health` | 各平台登录状态 |
+| `webapi login [<platform>] [--account <id>]` | 登录并捕获凭证（不给参数则交互式选择平台/账号） |
+| `webapi logout [<platform>] [--account <id>]` | 删除某账号的凭证（不给参数则交互式选择） |
+
+脚本 / CI 里用非交互写法（`--yes` 跳过确认）：
+
+```bash
+webapi login chatglm --account acc2 --yes
+webapi logout chatglm --account acc2 --yes
+```
+
+## 模型
+
+| 模型名 | 说明 |
+|---|---|
+| `mix` | 自动选择可用平台（当前即 chatglm） |
+| `chatglm` | 平台名模型，只跨账号、不跨平台 |
+| `glm-4` / `glm-3` | ChatGLM 的具体模型别名 |
+
+## 多账号（可选，但推荐）
+
+加第二个账号后，服务会启用**辅助通道**：压缩历史/工具调用转换等辅助任务
+会在另一个账号的独立页面上跑，与你的主对话**真正并行**，不再排队。
+
+再跑一次 `webapi login` 选「添加新账号」即可，**账号名会自动从登录身份派生**
+（用户名 → uid），不用自己想名字：
+
+```bash
+webapi login
+#   要登录哪个平台？        → ChatGLM (智谱)
+#   这次要做什么？          → ➕ 添加新账号
+#   ...手动登录另一个账号...
+#   ✔ 凭证已保存   账号: alice
+```
+
+选错了随时可以退：二级菜单里有 `← 返回上一步（重新选平台）`，
+平台菜单里有 `✗ 退出`；任何时候按 `Esc` / `Ctrl+C` 也会取消。
+（用 `webapi login <platform>` 明确指定平台时，菜单里给的是 `✗ 取消` —— 没有上一步可回。）
+
+> ⚠️ **两个账号必须是不同的人。** 系统浏览器很可能还留着上一个账号的登录态，
+> 抓到同一个人时服务会以为「有两个账号」并启用并行，结果两边打同一个账号，
+> 立刻收到「请等待其他对话生成完毕」。所以服务会**校验身份与 Cookie**：
+> - 抓到的和已有账号是同一个登录态 → 提示你选择「更新该账号 / 另存为新账号 / 取消」
+> - 非交互时（脚本）默认**更新原账号**，绝不悄悄多出一个重名账号
+
+用 `webapi accounts` 核对身份与角色分配。主/辅角色**启动时随机分配**以摊平额度消耗；
+需要钉死时用环境变量：
+
+```bash
+CHATGLM_MAIN_ACCOUNT=acc2 webapi start
+```
+
+## 配置
+
+放在项目目录的 `.env`，或直接用环境变量：
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `API_HOST` / `API_PORT` | `0.0.0.0` / `8631` | 监听地址与端口 |
+| `API_PREFIX` | `/v1` | 路由前缀 |
+| `REQUEST_TIMEOUT` | `300` | 请求超时（秒） |
+| `RATE_LIMIT_ENABLED` | `false` | 是否限流 |
+| `RATE_LIMIT_PER_MINUTE` | `60` | 每客户端每分钟请求数 |
+| `API_KEYS` | 空 | 逗号分隔的密钥列表 |
+| `API_KEY_REQUIRED` | `false` | 是否**强制**校验（配了密钥才生效） |
+| `DEBUG_LOGS` | `false` | 是否写 `~/.ai-api/logs/debug_*.log` |
+| `AUTH_DIR` | `~/.ai-api/auth` | 凭证目录 |
+| `LOG_DIR` | `logs` | 运行日志与 API 记录目录 |
+| `CHATGLM_MAIN_ACCOUNT` | 随机 | 钉死主通道账号 |
+| `BROWSER_HEADLESS` | 见实现 | `true` 时无头运行（服务器部署用） |
+| `WEBAIAPI_SKIP_BROWSER_INSTALL` | — | 设 1 跳过安装期的浏览器下载 |
+
+凭证、历史数据库、调试日志都在 `~/.ai-api/` 下。
+
+## 常见问题
+
+**「请求过于频繁，请稍后再试」**
+多半是**未登录**（访客额度用完了）。重新登录：`webapi login chatglm`。
+
+**抓到的账号不是我想登的那个**
+系统浏览器里往往还留着上一个账号的登录态。先在该页面**退出登录**，再登目标账号。
+
+**第一次对话很慢（20s+）**
+首次需要启动浏览器 + 导航 + 探测登录态。之后同会话会复用页面，
+准备阶段降到 0~3s。
+
+**任务跑一半停了、文件没改**
+网页端模型有时会「只写计划不调工具」。服务会自动再驱动一轮；
+若仍反复出现，把任务拆小一点（例如一次只让它改一个文件）。
+
+**怎么看到底发生了什么**
+- `logs/api_requests.log` —— 请求/响应**原样记录、不做加工**，每次启动重置
+- `logs/chatglm_sse_last.txt` —— 最近一轮的原始 SSE 报文（排查上游格式变化）
+
+## 开发
+
+```bash
+npm install        # 会自动 build（package.json 的 prepare 脚本）
+npm run dev        # 直接跑 tsx src/cli.ts，不用先构建
+npm run typecheck
+npm test           # 326 个单测
+npm run build      # 产出 dist/
+```
+
+## 许可
+
+MIT

package/bin/webapi.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * `webapi` 的可执行入口（`bin` 指向这里）。
+ *
+ * ## 为什么不让 `bin` 直接指向 `dist/cli.js`
+ * `dist/` 是**构建产物且被 .gitignore 忽略**。全新 clone 之后、或通过
+ * `npm i github:<user>/<repo>` 安装时，`dist/` 可能根本不存在。此时若 bin 直接
+ * 指向它，用户看到的是 shell 的原始报错：
+ *
+ * ```
+ * /bin/bash: 行 1: /usr/local/bin/webapi: 没有那个文件或目录
+ * ```
+ *
+ * —— 既没说"没构建"，也没说该怎么办。（实测确认过。）
+ *
+ * 所以这里放一个**提交进版本库**的薄入口：它永远存在，`dist/` 缺失时给出
+ * 可执行的提示。`bin/` 也是大家约定俗成会去找入口的位置。
+ *
+ * ## ⚠️ 为什么要显式调用 `runCli()`，而不是只 import
+ * `dist/cli.js` 里有一个「是否被直接执行」的守卫（比较 `process.argv[1]` 与
+ * `import.meta.url` 的 realpath）。经本文件 import 时，`argv[1]` 是
+ * `.../bin/webapi.mjs` 而 `import.meta.url` 是 `.../dist/cli.js` —— **两者不等**，
+ * 守卫会判定"不是直接执行"从而**什么都不做**（静默失效，最难查的一类 bug）。
+ * 因此这里必须显式调用导出的 `runCli()`。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(here, '..', 'dist', 'cli.js');
+
+if (!existsSync(cliPath)) {
+  console.error(
+    '[webapi] 还没有构建，找不到 dist/cli.js。\n' +
+      '       请先运行：  npm run build\n' +
+      '       （若你是 clone 下来做开发的：npm install 会自动构建，\n' +
+      '        该步骤由 package.json 的 `prepare` 脚本触发。）',
+  );
+  process.exit(1);
+}
+
+// 显式调用，不依赖 cli.js 内部的「直接执行」守卫（原因见文件头注释）
+const { runCli } = await import(pathToFileURL(cliPath).href);
+process.exitCode = await runCli();

package/dist/browser/auth-capture.d.ts

@@ -0,0 +1,110 @@
+import { type AccountInfo, type AuthRecord } from './credentials.js';
+/** 捕获到的凭证（写入文件的形状）。 */
+export interface CapturedAuth extends AuthRecord {
+    cookies?: AuthRecord['cookies'];
+    cookie_str?: string;
+    bearer?: string;
+    user_agent?: string;
+    captured_at?: number;
+    platform?: string;
+    account_info?: AccountInfo;
+    sample_requests?: Array<Record<string, unknown>>;
+}
+/**
+ * 调用平台 user info API 丰富账号信息（捕获后立即调用）。
+ *
+ * 失败时返回同步提取的结果（{@link extractAccountInfoSync}）。
+ *
+ * ⚠️ `platform === 'chatglm'` **直接短路**：它的 JWT 里已经含用户名，
+ * 而调它的 user info API 需要 `x-sign` 签名（我们没有）。
+ */
+export declare function fetchAccountInfo(platform: string, auth: AuthRecord): Promise<AccountInfo>;
+export interface AuthCaptureOptions {
+    authDir?: string;
+    /** 是否无头。凭证捕获**建议 false**（用户需要看到浏览器才能登录）。 */
+    headless?: boolean;
+    /** 捕获超时（秒）。目前仅用于提示，实际由用户的 Enter 决定。 */
+    captureTimeout?: number;
+    /** 账号 ID（同平台多账号）。 */
+    accountId?: string;
+    /**
+     * 捕获结束后是否**立即落盘**（默认 `true`）。
+     *
+     * 交互式流程（`login-flow.ts`）传 `false`：它要先看捕获到的**身份**、
+     * 问用户「这份凭证存成哪个账号」，再调 {@link AuthCapture.saveAs} 写。
+     * 若照旧立即写，就会先落一个 `__new__<ts>.json` 再改名 —— 中途崩溃会留下
+     * 一个「看起来像账号文件」的残骸（`listAccounts` 跳过它，但人肉 ls 会看到）。
+     */
+    saveOnCapture?: boolean;
+}
+export declare class AuthCapture {
+    readonly platform: string;
+    private readonly authDir;
+    /** 用户传入的 `authDir`（`saveAs()` 重算路径时要原样带上）。 */
+    private readonly authDirOption;
+    private readonly saveOnCapture;
+    private _accountId;
+    private _authFile;
+    private readonly headless;
+    private readonly captureTimeout;
+    private apiConfig;
+    private browser;
+    private context;
+    private page;
+    readonly capturedAuth: CapturedAuth;
+    constructor(platform: string, options?: AuthCaptureOptions);
+    /** 当前账号 ID（`saveAs()` 会改写它，调用方不要缓存）。 */
+    get accountId(): string;
+    /** 当前目标文件路径（随 `saveAs()` 变化）。 */
+    get authFile(): string;
+    /** 启动浏览器、引导用户登录、抓取凭证并落盘。 */
+    capture(): Promise<CapturedAuth>;
+    /** 请求回调：抓 bearer / 额外请求头 / 样本请求。 */
+    private onRequest;
+    /** 抓 cookies 与 User-Agent。 */
+    private captureCookiesAndUa;
+    /**
+     * 保存凭证。
+     *
+     * 三重保护（避免「重登把另一个账号冲掉」这个最常见的损失）：
+     * 1. 已有文件先备份为 `.bak`；
+     * 2. 先写临时文件再 `rename`（原子替换，中途崩溃不会留下半截 JSON）；
+     * 3. 权限设为 0600（仅所有者可读写）。
+     */
+    private saveAuth;
+    /**
+     * 以指定账号 ID 落盘（交互式流程在「拿到身份、确认账号名」之后调用）。
+     *
+     * 复用 {@link saveAuth} 的三重保护（备份 `.bak` → 临时文件 → 原子 rename → 0600），
+     * 所以覆盖旧账号时同样是安全的。
+     *
+     * ⚠️ `accountId` 会被**当成文件名**使用，必须校验：它可能来自平台返回的身份
+     * 字符串（`slugAccountId` 已经清洗过一道），但这里是最后一道闸 ——
+     * 不能让 `../` 之类的东西写出去。
+     *
+     * @returns 最终写入的文件路径
+     */
+    saveAs(accountId: string): string;
+    /**
+     * 账号 ID 能不能当文件名用。
+     *
+     * 分两档，**不能合并成一条严格正则**：
+     * 1. **硬性禁止**：`/` `\` NUL、空串、`.`、`..` —— 这条对「新账号」和
+     *    「更新已有账号」都成立（防路径穿越）。
+     * 2. **严格字符集**（字母数字 `._-`）：只用来约束**新**账号名。
+     * 3. **放宽**：名字**已经存在于磁盘**时允许任意其它字符 —— 真实用户目录里
+     *    就有 `用户_bFa15b` 这种（早期手工登录留下的），用严格正则会把
+     *    「重新登录这个账号」直接判成非法，用户只能删号重登。
+     *    安全性由 `listAccounts` 保证：它的值来自 `readdirSync`，是普通文件名。
+     */
+    private isAcceptableAccountId;
+    /** 清理浏览器资源。 */
+    private cleanup;
+}
+/**
+ * 交互式捕获入口（CLI 的 `login` 命令调用）。
+ *
+ * @returns 进程退出码（0 成功）
+ */
+export declare function capturePlatformAuth(platform: string, accountId?: string): Promise<number>;
+//# sourceMappingURL=auth-capture.d.ts.map

package/dist/browser/auth-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-capture.d.ts","sourceRoot":"","sources":["../../src/browser/auth-capture.ts"],"names":[],"mappings":"AA2BA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,kBAAkB,CAAC;AAW1B,uBAAuB;AACvB,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAiBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAuF/F;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IAExC,OAAO,CAAC,UAAU,CAAS;IAE3B,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,OAAO,CAAC,SAAS,CAAqD;IAEtE,OAAO,CAAC,OAAO,CAAwB;IAEvC,OAAO,CAAC,OAAO,CAA+B;IAE9C,OAAO,CAAC,IAAI,CAAqB;IAEjC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAM;IAEzC,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,EA8B7D;IAED,wCAAwC;IACxC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,iCAAiC;IACjC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,4BAA4B;IACtB,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAqErC;IAED,oCAAoC;YACtB,SAAS;IAsEvB,8BAA8B;YAChB,mBAAmB;IAoBjC;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ;IA4BhB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAYhC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAQ7B,eAAe;YACD,OAAO;CAYtB;AAMD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAmClG"}