@zhin.js/adapter-douyin-live 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# @zhin.js/adapter-douyin-live
 
-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.
+> **Experimental · 非官方协议** — 基于抖音直播网页端 **非官方、未公开** 的弹幕 WebSocket（`webcast/im/push/v2`）与页面数据，**随时可能因平台改版、签名升级或风控而失效**；不进 stable smoke，接口与配置可能不兼容变更。使用前请自行确认符合抖音用户协议，仅用于**你自己的直播间**。
+
+> 🚧 **当前只听不说**：`sendMode` 默认 `off`。`sendMode: direct` 尚未实现（没有稳定、可测试的发弹幕接口），发送会明确返回 `not_implemented`，回复不会出现在直播间。
+
+账号由 `DouyinLiveAdapter` 管理。Endpoint 直接继承实际 `DouyinLiveClient`，保留原生方法与事件；框架生命周期、规范入站与发送经 `endpointSpec` 和 AdapterIndex 接入，不占用 Client 的原生方法。
+
+`Session.event` 使用 Client 已公开的 `DouyinLiveChat`（`uid`、`nickname`、`text`、`timestamp`、可选 `id` / `roomId`）事件对象，与 `danmaku` 事件保持同一引用。网络帧经包内最小 protobuf 解码器解析，未作为公开事件 DTO。
+
+Zhin.js 抖音直播弹幕适配器（Plugin Runtime）：让 Bot 在**你自己的直播间**里看弹幕，弹幕与 B 站直播弹幕一样进入 Agent 的弹幕窗口。设计见 [ADR 0038：连续输入合流——高热群与弹幕](https://github.com/zhinjs/zhin/blob/main/docs/adr/0038-continuous-input-merge.md) §5，讨论见 [#1049](https://github.com/zhinjs/zhin/issues/1049)、[#1135](https://github.com/zhinjs/zhin/issues/1135)。
+
+## 先读这几条
+
+- **非官方协议，随时会坏**：房间号解析、WebSocket 地址参数、`signature` 签名、protobuf 字段都来自对网页端的观察，平台一改就失效。失效时连接会反复失败并退避重连，请关注日志。
+- **签名不内置**：平台要求 WebSocket 地址带 `signature`（由网页端混淆脚本生成）。本包**不内置、不 vendor** 任何平台脚本或第三方抓取器；可配 `signerUrl` 指向你自己部署的签名服务。不配时不带签名连接，**平台可能直接拒绝握手**。
+- **一窗只回一条**：本适配器声明 `liveDanmaku` 能力。Agent 不逐条回弹幕，而是把一段时间内的弹幕收进窗口，由模型挑一条（或总结后）回一次。窗口参数见下文「弹幕窗口」。
+- **弹幕回合只读**：弹幕回合按匿名观众的权限跑，只开放声明了 `readOnly: true` 的工具，不出任何审批卡，不跑 Shell / MCP / 子 Agent。
+- **默认只听不说（sendMode α）**：`sendMode` 默认 `off`；`direct` 目前只做房间与内容校验，然后返回 `not_implemented`，不会调用任何平台写接口。
+- **Cookie 等同账号凭据**：`cookie` 可选（不填时启动时申请游客 `ttwid`）。若填写浏览器 Cookie，**用环境变量注入，不要写进 `zhin.config.yml` 明文，不要提交到仓库，不要贴进日志或 issue**。本包从不记录 Cookie。
+- **只进自己的直播间**：只连 `roomId` 指定的一个房间。禁止用于营销、引流、刷屏或采集他人直播间数据。
+
+## 当前能力
+
+| 能力 | 状态 |
+|---|---|
+| web_rid → 内部 room_id（直播间页内嵌数据），游客 `ttwid` | ✅ 已实现（每次重连重新解析） |
+| 弹幕 WebSocket：10 秒 `hb` 心跳、`needAck` 回 ack、看门狗、断线退避重连 | ✅ 已实现 |
+| 解 gzip `PushFrame` → `Response`，只解析 `WebcastChatMessage` | ✅ 已实现（礼物、进场、点赞、关注等忽略） |
+| 按消息 id 去重（最近 500 条） | ✅ 已实现 |
+| WebSocket `signature` | 🚧 不内置；可配 `signerUrl` 外部签名服务 |
+| 发弹幕（`sendMode: direct`） | 🚧 未实现，返回 `not_implemented` |
+| 过滤自己发的弹幕 | 🚧 暂无（本包不发弹幕，也不识别登录账号） |
+| 礼物 / 进场 / 点赞 / 关注事件、扫码登录、多直播间、Console 页面 | 🚧 未做 |
+
+## 前置条件
+
+1. 你自己的抖音直播间 web_rid（`https://live.douyin.com/<web_rid>` 里的数字）作为 `roomId`
+2. 可选：浏览器 Cookie 整串，放进 `.env`（已被 gitignore）：`DOUYIN_LIVE_COOKIE`。不填则使用游客 `ttwid`
+3. 可选：自建签名服务地址 `signerUrl`（见下文「签名」）
+4. Agent 已启用（`ai.agent`）：弹幕窗口由 Agent 的 `inboundQueue.live` 驱动
+
+## 最小配置
+
+```yaml
+configVersion: 2
+plugins:
+  douyin-live: "@zhin.js/adapter-douyin-live"
+douyin-live:
+  sendMode: off             # 默认；direct 尚未实现（返回 not_implemented）
+  maxLength: 50             # 为后续 direct 发送预留
+  maxChunks: 2
+  minSendIntervalSec: 5
+  endpoints:
+    - id: my-live
+      roomId: "123456789"   # web_rid；只填你自己的直播间
+      cookie: ${DOUYIN_LIVE_COOKIE}
+      # signerUrl: http://127.0.0.1:8080/sign
+```
+
+必填字段（`endpoints[i]`）：`id`、`roomId`。
+
+## 签名
+
+连接前按网页端规则把固定的一组查询参数（`live_id`、`aid`、`version_code`、`webcast_sdk_version`、`room_id`、`user_unique_id`、`identity` 等）拼成 `k=v,k=v,...` 取 md5，得到 `X-MS-STUB`。配置了 `signerUrl` 时请求：
+
+```text
+GET <signerUrl>?stub=<X-MS-STUB>
+```
+
+响应为纯文本签名，或 JSON `{ "signature": "..." }`，结果作为 WebSocket 的 `signature` 参数。签名服务由你自行部署与维护，本包不提供实现。
+
+## 弹幕窗口
+
+窗口由 Agent 配置控制（不是本适配器的配置），与 `@zhin.js/adapter-bilibili-live` 相同：
+
+```yaml
+ai:
+  agent:
+    inboundQueue:
+      live:
+        mode: pick-one        # pick-one：挑一条回；summary：总结窗口后回一次
+        windowMs: 10000       # 第一条弹幕后等多久发车
+        minIntervalMs: 15000  # 两次弹幕回复的最小间隔
+```
+
+## 会话与消息
+
+| 字段 | 值 |
+|---|---|
+| `conversation` | `{ kind: 'channel', id: <web_rid> }`（与配置 `roomId` 一致） |
+| `message.id` | 平台消息 id（取不到时用时间戳 + uid + 序号） |
+| `sender.id` | 观众 user id；取不到时为 `anon:<昵称>` |
+| `metadata` | `{ roomId: <内部 room_id>, liveDanmaku: true }` |
+
+出站（将来 `direct`）只支持纯文本：Markdown 去格式，图片等其他段不支持；抖音弹幕没有「回复」字段，`mention` 折叠进正文 `@昵称`。
+
+## 磁盘占用
+
+本适配器不落盘：去重表（最近 500 条消息 id）与连接状态都在内存里，重启即清空。
+
+## 已知限制
+
+- 平台协议非公开，字段与签名随时可能变化；不签名时可能无法连接。
+- 取不到 uid 的观众按昵称区分，同名观众会被当成同一个人。
+- 本切片不提供 Console 页面与 RPC。
+
+## 故障排查
+
+| 现象 | 原因与处理 |
+|---|---|
+| 日志 `douyin_live_unsigned` | 未配 `signerUrl`，不带签名连接。若握手被拒，部署签名服务后配 `signerUrl` |
+| `Douyin live page returned no room_id` | 直播间未开播、web_rid 填错，或页面改版。核对 `roomId` |
+| `Douyin live did not issue a ttwid cookie` | 游客 Cookie 申请失败（风控 / 网络）。可在 `cookie` 里带上浏览器的 `ttwid` |
+| 连接反复断开重连 | 签名失效、Cookie 失效或协议改版；看门狗 30 秒无数据也会重连 |
+| 发送返回 `send_disabled` | `sendMode: off`（默认），只听不说 |
+| 发送返回 `not_implemented` | `sendMode: direct` 尚未实现，改回 `off` |

package/adapters/douyin-live/index.js

@@ -0,0 +1,26 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/douyin-live/index.ts` → defineAdapter.
+ * Experimental：连抖音直播弹幕 WebSocket（非官方协议）；声明 `liveDanmaku`，Agent 按弹幕窗口一窗只回一条（ADR 0038 §5）。
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { DouyinLiveAdapter } from "../../lib/adapter.js";
+export { DouyinLiveEndpoint } from "../../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound', 'liveDanmaku'],
+    // 弹幕只支持纯文本；平台没有「回复」字段，mention 折叠进正文 `@昵称`。
+    profile: {
+        default: {
+            messaging: {
+                segments: {
+                    supported: ['text', 'mention'],
+                    html: 'text',
+                    markdown: 'text',
+                    interactive: 'text',
+                },
+            },
+            delivery: { send: true, spool: true },
+        },
+    },
+    createAdapter: context => new DouyinLiveAdapter(context),
+});

package/adapters/douyin-live/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Convention entry: discover `adapters/douyin-live/index.ts` → defineAdapter.
+ * Experimental：连抖音直播弹幕 WebSocket（非官方协议）；声明 `liveDanmaku`，Agent 按弹幕窗口一窗只回一条（ADR 0038 §5）。
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { DouyinLiveAdapter } from '../../src/adapter.js';
+import type { DouyinLiveEndpointConfig } from '../../src/protocol.js';
+
+export { DouyinLiveEndpoint } from '../../src/endpoint.js';
+export type { DouyinLiveEndpointOptions } from '../../src/endpoint.js';
+
+export default defineAdapter<DouyinLiveEndpointConfig>({
+  capabilities: ['inbound', 'outbound', 'liveDanmaku'],
+  // 弹幕只支持纯文本；平台没有「回复」字段，mention 折叠进正文 `@昵称`。
+  profile: {
+    default: {
+      messaging: {
+        segments: {
+          supported: ['text', 'mention'],
+          html: 'text',
+          markdown: 'text',
+          interactive: 'text',
+        },
+      },
+      delivery: { send: true, spool: true },
+    },
+  },
+  createAdapter: context => new DouyinLiveAdapter(context),
+});

package/lib/adapter.d.ts

@@ -0,0 +1,17 @@
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import type { DouyinLiveClientEventMap } from './client.js';
+import { DouyinLiveEndpoint } from './endpoint.js';
+import { type DouyinLiveEndpointConfig } from './protocol.js';
+export declare class DouyinLiveAdapter extends Adapter<DouyinLiveEndpoint, DouyinLiveEndpointConfig, DouyinLiveClientEventMap> {
+    constructor(_context: AdapterContext<DouyinLiveEndpointConfig>);
+    get configurationIdentityFields(): readonly string[];
+    /** `cookie` 是账号凭据且无身份探针可校验，故不在可热更新字段里：换 Cookie 需显式替换 endpoint。 */
+    get configurationUpdateFields(): readonly string[];
+    protected validateConfiguration(config: DouyinLiveEndpointConfig): void;
+    protected createEndpoint(input: DouyinLiveEndpointConfig, execution: EndpointCreationContext): DouyinLiveEndpoint;
+}
+declare module '@zhin.js/feature-kit' {
+    interface AdapterRegistry {
+        readonly 'douyin-live': DouyinLiveAdapter;
+    }
+}

package/lib/adapter.js

@@ -0,0 +1,15 @@
+import { Adapter } from 'zhin.js/adapter';
+import { DouyinLiveEndpoint } from './endpoint.js';
+import { resolveDouyinLiveConfig } from './protocol.js';
+export class DouyinLiveAdapter extends Adapter {
+    constructor(_context) { super(); }
+    get configurationIdentityFields() { return ['id']; }
+    /** `cookie` 是账号凭据且无身份探针可校验，故不在可热更新字段里：换 Cookie 需显式替换 endpoint。 */
+    get configurationUpdateFields() {
+        return ['roomId', 'sendMode', 'maxLength', 'maxChunks', 'minSendIntervalSec', 'signerUrl'];
+    }
+    validateConfiguration(config) { resolveDouyinLiveConfig(config); }
+    createEndpoint(input, execution) {
+        return new DouyinLiveEndpoint({ id: execution.canonicalId, config: resolveDouyinLiveConfig(input), signal: execution.signal });
+    }
+}

package/lib/client.d.ts

@@ -0,0 +1,73 @@
+import type { DouyinLiveChat, ResolvedDouyinLiveConfig } from './protocol.js';
+export type DouyinLiveFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+        getSetCookie?(): string[];
+    };
+    text(): Promise<string>;
+}>;
+/**
+ * 由 `X-MS-STUB`（参数串 md5）算出 WebSocket `signature`。
+ * 返回空串 / 缺失视为签名失败并抛错（不会静默降级为无签名）；想无签名连接就不要配置 signer。
+ * `signal` 带 15 s 请求超时与客户端取消。
+ */
+export type DouyinLiveSigner = (stub: string, signal?: AbortSignal) => Promise<string> | string;
+export interface DouyinLiveRoomInfo {
+    /** 平台内部 room_id（WebSocket 用）。 */
+    readonly roomId: string;
+}
+export declare const DOUYIN_LIVE_PUSH_URL = "wss://webcast100-ws-web-lq.douyin.com/webcast/im/push/v2/";
+/** 平台会拒绝明显的非浏览器 UA；与 `browser_version` 参数保持一致。 */
+export declare const DOUYIN_LIVE_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36";
+export declare class DouyinLiveApiError extends Error {
+    readonly httpStatus?: number;
+    constructor(message: string, httpStatus?: number);
+}
+/**
+ * `X-MS-STUB` = md5(`k1=v1,k2=v2,...`)，按 `STUB_KEYS` 顺序取 WebSocket 查询参数。
+ * md5 是平台协议规定的参数摘要（不是安全用途）；输入只有公开参数与随机游客设备 id，不含 Cookie 或账号凭据。
+ */
+export declare function buildSignatureStub(params: ReadonlyMap<string, string> | Record<string, string>): string;
+export declare class DouyinLiveClient {
+    #private;
+    readonly config: ResolvedDouyinLiveConfig;
+    readonly fetch: DouyinLiveFetch;
+    readonly now: () => number;
+    /** 游客设备 id：同一 endpoint 生命周期内固定。 */
+    readonly userUniqueId: string;
+    constructor(config: ResolvedDouyinLiveConfig, fetch: DouyinLiveFetch, options?: {
+        readonly now?: () => number;
+        readonly signal?: AbortSignal;
+        readonly sign?: DouyinLiveSigner;
+        readonly userUniqueId?: string;
+    });
+    /** 是否已有 `ttwid`（配置 Cookie 自带或已申请到游客 ttwid）。 */
+    get hasTtwid(): boolean;
+    /** 是否能生成 WebSocket `signature`。 */
+    get canSign(): boolean;
+    /** 连接 / 请求用的 Cookie：配置 Cookie 原样保留，缺 `ttwid` 时补上游客 ttwid。 */
+    cookieHeader(extra?: Record<string, string>): string;
+    /** 没有 `ttwid` 时访问直播首页申请游客 ttwid（平台经 Set-Cookie 下发）。 */
+    ensureTtwid(): Promise<void>;
+    /** web_rid → 内部 room_id：解析直播间页内嵌数据。每次（重）连都重新取。 */
+    resolveRoom(): Promise<DouyinLiveRoomInfo>;
+    /** 弹幕 WebSocket 查询参数（不含 signature）。 */
+    pushParams(roomId: string): Map<string, string>;
+    /** 弹幕 WebSocket 地址；能签名时追加 `signature`，否则不带（平台可能拒绝握手）。 */
+    buildPushUrl(roomId: string): Promise<string>;
+    /**
+     * 取签名：优先注入的 signer，其次 `signerUrl`；都没有返回空串（unsigned）。
+     * 配了签名来源却拿不到可用签名时抛错（可见、可重试），不静默降级成无签名连接。
+     */
+    signature(stub: string): Promise<string>;
+}
+/** 直播间页内嵌 JSON（转义或未转义）里的 `roomId`。 */
+export declare function parseRoomIdFromHtml(html: string): string | undefined;
+/** 原生事件：`danmaku`（解析后的 `WebcastChatMessage`）。 */
+export type DouyinLiveClientEventMap = Record<string, DouyinLiveChat>;

package/lib/client.js

@@ -0,0 +1,236 @@
+/**
+ * 抖音直播 Web 侧 client（非官方协议，Experimental）。
+ * 读：游客 `ttwid`、直播间页 → 内部 room_id、弹幕 WebSocket 地址（含可选 signature）。
+ * 本包不做发弹幕（sendMode α），也不内置平台混淆签名脚本。永远不要记录 Cookie。
+ */
+import { createHash, randomInt } from 'node:crypto';
+const REQUEST_TIMEOUT_MS = 15_000;
+const LIVE_BASE_URL = 'https://live.douyin.com';
+export const DOUYIN_LIVE_PUSH_URL = 'wss://webcast100-ws-web-lq.douyin.com/webcast/im/push/v2/';
+/** 平台会拒绝明显的非浏览器 UA；与 `browser_version` 参数保持一致。 */
+export const DOUYIN_LIVE_USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+/** `X-MS-STUB` 参与 md5 的参数（顺序固定，取自网页端 SDK）。 */
+const STUB_KEYS = [
+    'live_id', 'aid', 'version_code', 'webcast_sdk_version', 'room_id', 'sub_room_id', 'sub_channel_id',
+    'did_rule', 'user_unique_id', 'device_platform', 'device_type', 'ac', 'identity',
+];
+const MAX_SIGNATURE_LENGTH = 512;
+export class DouyinLiveApiError extends Error {
+    httpStatus;
+    constructor(message, httpStatus) {
+        super(message);
+        this.name = 'DouyinLiveApiError';
+        if (httpStatus !== undefined)
+            this.httpStatus = httpStatus;
+    }
+}
+/**
+ * `X-MS-STUB` = md5(`k1=v1,k2=v2,...`)，按 `STUB_KEYS` 顺序取 WebSocket 查询参数。
+ * md5 是平台协议规定的参数摘要（不是安全用途）；输入只有公开参数与随机游客设备 id，不含 Cookie 或账号凭据。
+ */
+export function buildSignatureStub(params) {
+    const get = (key) => (params instanceof Map ? params.get(key) : params[key]) ?? '';
+    const plain = STUB_KEYS.map((key) => `${key}=${get(key)}`).join(',');
+    return createHash('md5').update(plain).digest('hex');
+}
+function cookieValue(cookie, name) {
+    if (!cookie)
+        return undefined;
+    for (const part of cookie.split(';')) {
+        const index = part.indexOf('=');
+        if (index > 0 && part.slice(0, index).trim() === name) {
+            const value = part.slice(index + 1).trim();
+            if (value)
+                return value;
+        }
+    }
+    return undefined;
+}
+function randomDigits(length) {
+    let out = String(randomInt(1, 10));
+    while (out.length < length)
+        out += String(randomInt(0, 10));
+    return out;
+}
+function randomHex(length) {
+    let out = '';
+    while (out.length < length)
+        out += randomInt(0, 16).toString(16);
+    return out;
+}
+export class DouyinLiveClient {
+    config;
+    fetch;
+    now;
+    #signer;
+    #signal;
+    #ttwid;
+    /** 游客设备 id：同一 endpoint 生命周期内固定。 */
+    userUniqueId;
+    constructor(config, fetch, options = {}) {
+        this.config = config;
+        this.fetch = fetch;
+        this.now = options.now ?? Date.now;
+        this.#signal = options.signal;
+        this.#signer = options.sign;
+        this.#ttwid = cookieValue(config.cookie, 'ttwid');
+        this.userUniqueId = options.userUniqueId ?? randomDigits(19);
+    }
+    /** 是否已有 `ttwid`（配置 Cookie 自带或已申请到游客 ttwid）。 */
+    get hasTtwid() {
+        return Boolean(this.#ttwid);
+    }
+    /** 是否能生成 WebSocket `signature`。 */
+    get canSign() {
+        return Boolean(this.#signer || this.config.signerUrl);
+    }
+    /** 连接 / 请求用的 Cookie：配置 Cookie 原样保留，缺 `ttwid` 时补上游客 ttwid。 */
+    cookieHeader(extra = {}) {
+        const parts = [];
+        if (this.config.cookie)
+            parts.push(this.config.cookie.replace(/;\s*$/, ''));
+        if (this.#ttwid && !cookieValue(this.config.cookie, 'ttwid'))
+            parts.push(`ttwid=${this.#ttwid}`);
+        for (const [key, value] of Object.entries(extra)) {
+            if (!cookieValue(this.config.cookie, key))
+                parts.push(`${key}=${value}`);
+        }
+        return parts.join('; ');
+    }
+    #requestSignal() {
+        const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+        return this.#signal ? AbortSignal.any([this.#signal, timeout]) : timeout;
+    }
+    async #get(url, headers = {}) {
+        this.#signal?.throwIfAborted();
+        const response = await this.fetch(url, {
+            method: 'GET',
+            headers: { 'user-agent': DOUYIN_LIVE_USER_AGENT, ...headers },
+            signal: this.#requestSignal(),
+        });
+        this.#signal?.throwIfAborted();
+        if (!response.ok)
+            throw new DouyinLiveApiError(`HTTP ${response.status}`, response.status);
+        return response;
+    }
+    /** 没有 `ttwid` 时访问直播首页申请游客 ttwid（平台经 Set-Cookie 下发）。 */
+    async ensureTtwid() {
+        if (this.#ttwid)
+            return;
+        const response = await this.#get(`${LIVE_BASE_URL}/`);
+        const cookies = typeof response.headers.getSetCookie === 'function'
+            ? response.headers.getSetCookie()
+            : [response.headers.get('set-cookie') ?? ''];
+        for (const line of cookies) {
+            const match = /(?:^|[;,]\s*)ttwid=([^;,\s]+)/.exec(line);
+            if (match?.[1]) {
+                this.#ttwid = match[1];
+                return;
+            }
+        }
+        throw new DouyinLiveApiError('Douyin live did not issue a ttwid cookie');
+    }
+    /** web_rid → 内部 room_id：解析直播间页内嵌数据。每次（重）连都重新取。 */
+    async resolveRoom() {
+        await this.ensureTtwid();
+        const response = await this.#get(`${LIVE_BASE_URL}/${encodeURIComponent(this.config.roomId)}`, {
+            cookie: this.cookieHeader({ __ac_nonce: `0${randomHex(20)}` }),
+            referer: `${LIVE_BASE_URL}/`,
+        });
+        const html = await response.text();
+        const roomId = parseRoomIdFromHtml(html);
+        if (!roomId)
+            throw new DouyinLiveApiError('Douyin live page returned no room_id (room offline or page changed)');
+        return Object.freeze({ roomId });
+    }
+    /** 弹幕 WebSocket 查询参数（不含 signature）。 */
+    pushParams(roomId) {
+        const nowMs = Math.floor(this.now());
+        // 随机游客设备 id（非账号身份、非秘密）；平台把它同时用作 did 与 user_unique_id。
+        const deviceId = this.userUniqueId;
+        return new Map([
+            ['app_name', 'douyin_web'], ['version_code', '180800'], ['webcast_sdk_version', '1.0.14-beta.0'],
+            ['update_version_code', '1.0.14-beta.0'], ['compress', 'gzip'], ['device_platform', 'web'],
+            ['cookie_enabled', 'true'], ['screen_width', '1536'], ['screen_height', '864'],
+            ['browser_language', 'zh-CN'], ['browser_platform', 'Win32'], ['browser_name', 'Mozilla'],
+            ['browser_version', DOUYIN_LIVE_USER_AGENT.slice('Mozilla/'.length)], ['browser_online', 'true'],
+            ['tz_name', 'Asia/Shanghai'], ['cursor', `d-1_u-1_fh-0_t-${nowMs}_r-1`],
+            ['internal_ext', `internal_src:dim|wss_push_room_id:${roomId}|wss_push_did:${deviceId}|first_req_ms:${nowMs}|fetch_time:${nowMs}|seq:1|wss_info:0-${nowMs}-0-0`],
+            ['host', LIVE_BASE_URL], ['aid', '6383'], ['live_id', '1'], ['did_rule', '3'], ['endpoint', 'live_pc'],
+            ['support_wrds', '1'], ['user_unique_id', deviceId], ['im_path', '/webcast/im/fetch/'], ['identity', 'audience'],
+            ['need_persist_msg_count', '15'], ['insert_task_id', ''], ['live_reason', ''], ['room_id', roomId],
+            ['heartbeatDuration', '0'],
+        ]);
+    }
+    /** 弹幕 WebSocket 地址；能签名时追加 `signature`，否则不带（平台可能拒绝握手）。 */
+    async buildPushUrl(roomId) {
+        const params = this.pushParams(roomId);
+        const signature = await this.signature(buildSignatureStub(params));
+        if (signature)
+            params.set('signature', signature);
+        const query = [...params].map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join('&');
+        return `${DOUYIN_LIVE_PUSH_URL}?${query}`;
+    }
+    /**
+     * 取签名：优先注入的 signer，其次 `signerUrl`；都没有返回空串（unsigned）。
+     * 配了签名来源却拿不到可用签名时抛错（可见、可重试），不静默降级成无签名连接。
+     */
+    async signature(stub) {
+        let value;
+        if (this.#signer) {
+            const signal = this.#requestSignal();
+            signal.throwIfAborted();
+            value = await withAbort(Promise.resolve().then(() => this.#signer(stub, signal)), signal);
+        }
+        else if (this.config.signerUrl) {
+            const separator = this.config.signerUrl.includes('?') ? '&' : '?';
+            const response = await this.#get(`${this.config.signerUrl}${separator}stub=${encodeURIComponent(stub)}`);
+            value = parseSignerResponse(await response.text());
+        }
+        else {
+            return '';
+        }
+        value = String(value ?? '').trim();
+        if (!value)
+            throw new DouyinLiveApiError('Douyin live signer returned an empty signature');
+        if (value.length > MAX_SIGNATURE_LENGTH || /[\s&#]/.test(value)) {
+            throw new DouyinLiveApiError('Douyin live signer returned an invalid signature');
+        }
+        return value;
+    }
+}
+/** 让不理会 signal 的注入 signer 也受请求超时 / 取消约束。 */
+function withAbort(promise, signal) {
+    // 超时 / 取消后 signer 仍可能 reject：始终挂上处理器，避免 unhandled rejection。
+    promise.catch(() => undefined);
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+/** 直播间页内嵌 JSON（转义或未转义）里的 `roomId`。 */
+export function parseRoomIdFromHtml(html) {
+    const patterns = [/roomId\\":\\"(\d+)\\"/, /"roomId":"(\d+)"/];
+    for (const pattern of patterns) {
+        const match = pattern.exec(html);
+        if (match?.[1] && !/^0+$/.test(match[1]))
+            return match[1];
+    }
+    return undefined;
+}
+function parseSignerResponse(body) {
+    const text = body.trim();
+    if (!text.startsWith('{'))
+        return text;
+    try {
+        const json = JSON.parse(text);
+        const value = json.signature ?? json['X-Bogus'] ?? json.data?.signature;
+        return typeof value === 'string' ? value : '';
+    }
+    catch {
+        return '';
+    }
+}

package/lib/endpoint.d.ts

@@ -0,0 +1,37 @@
+import { endpointSpec, type Endpoint, type EndpointSpecification } from 'zhin.js/adapter';
+import type { CapabilityId } from 'zhin.js';
+import { DouyinLiveClient, type DouyinLiveFetch, type DouyinLiveSigner } from './client.js';
+import { type ResolvedDouyinLiveConfig } from './protocol.js';
+/** 最小 WebSocket 面（`ws` 或测试替身）。 */
+export interface LiveSocket {
+    binaryType: string;
+    send(data: Uint8Array): void;
+    close(): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', listener: (event: {
+        data?: unknown;
+        code?: number;
+    }) => void): void;
+}
+/** 建连：需要自定义 `cookie` / `user-agent` 请求头，所以默认用 `ws` 而不是全局 WebSocket。 */
+export type LiveSocketFactory = (url: string, headers: Readonly<Record<string, string>>) => LiveSocket;
+export interface DouyinLiveEndpointOptions {
+    readonly id: CapabilityId;
+    readonly signal?: AbortSignal;
+    readonly config: ResolvedDouyinLiveConfig;
+    readonly fetch?: DouyinLiveFetch;
+    readonly socket?: LiveSocketFactory;
+    /** 可选签名函数（优先于 `config.signerUrl`）。 */
+    readonly sign?: DouyinLiveSigner;
+    readonly now?: () => number;
+    /** 固定游客设备 id（测试用）。 */
+    readonly userUniqueId?: string;
+}
+export declare class DouyinLiveEndpoint extends DouyinLiveClient implements Endpoint {
+    #private;
+    readonly [endpointSpec]: EndpointSpecification;
+    constructor(options: DouyinLiveEndpointOptions);
+    /** web_rid（会话 id，与配置 `roomId` 一致）。 */
+    get webRid(): string;
+    /** 平台内部 room_id（连上之后可用）。 */
+    get internalRoomId(): string | undefined;
+}