virlen-remote 0.1.0

package/src/protocol/hello.ts

@@ -0,0 +1,112 @@
+/**
+ * 版本与能力协商（见 docs/phone-control-bridge.md §3.5）。
+ *
+ * 规则：
+ * - 双方各自报能力集，**取交集**驱动 UI 显隐；
+ * - 主版本不匹配 → 拒绝并提示升级（**不要试图兼容**）；
+ * - 新方法只增不改；破坏性变更才升 major。
+ *
+ * 兼容性靠 **`E_UNSUPPORTED` 错误**而不是版本号 if-else —— 老端调新方法时明确报错，UI 隐藏该功能。
+ */
+import { BridgeError } from './errors'
+import type { StreamMode } from './api'
+import type { GrantRecord } from './identity'
+
+export interface ClientInfo {
+  platform: string
+  appVersion: string
+}
+
+/** 发起方（手机）hello 参数。 */
+export interface HelloParams {
+  protocolVersion: number
+  client: ClientInfo
+  capabilities: string[]
+  /**
+   * 配对令牌。
+   *
+   * - **首次配对**：二维码里的**一次性票据**（兑换后电脑端签发 `grant` 回传，见 §30.3）；
+   * - **已配对设备**：本地存储的**授权凭证**（`grant`，电脑端滑动续期）。
+   */
+  token?: string
+  /**
+   * 手机设备 key（`mk-…`，M6 新增，**可选**）。
+   *
+   * 为什么可选：已装机的旧版 PWA 不会带它。电脑端把它当作「临时设备」放行（凭证仍要有效），
+   * 等手机端更新后再回填绑定（§30.5 的渐进迁移）。
+   */
+  mobileKey?: string
+  /** 手机显示名（电脑端列表里显示；缺省由电脑端给「Virlen 手机」）。 */
+  mobileName?: string
+  /**
+   * 流式正文的接收偏好（§32，可选）。
+   *
+   * - 不传 / `'full'`：每帧发整段正文（旧行为，带宽 O(n²)）；
+   * - `'delta'`：只发新增后缀（带宽 O(n)）—— 客户端必须能按 `offset` 重基准。
+   *
+   * 为何用参数而不是能力标记：`capabilities` 是「我会什么」的集合，
+   * 而这里要的是「我这次要什么」—— 且 `stream.delta` 这个能力名在 M3 就被两端写进能力表
+   * 却始终没实现，已部署的旧客户端会「声明了但不会处理」。用一个**明确的一次性声明**
+   * 才能同时满足：老客户端不发它（继续收整帧）、新客户端发了才收到增量。
+   */
+  streamMode?: StreamMode
+}
+
+/** 应答方（电脑）hello 结果。 */
+export interface HelloResult {
+  protocolVersion: number
+  host: ClientInfo
+  capabilities: string[]
+  paired: boolean
+  deviceName: string
+  /** 电脑设备 key，手机据以保存设备记录（同时也是房间号的来源）。 */
+  deviceId?: string
+  /**
+   * 当前有效的授权凭证（**含首次配对新签发的那条**）。
+   *
+   * 手机端必须用它覆盖本地记录：首次配对时手机手上只有一次性票据，真正的长期凭证在这里；
+   * 已配对设备每次连接也会拿到（滑动续期后的到期时间）。
+   */
+  grant?: GrantRecord
+}
+
+export interface NegotiationInput {
+  protocolVersion: number
+  capabilities: readonly string[]
+}
+
+export interface Negotiated {
+  protocolVersion: number
+  /** 双方能力的交集（有序、去重，保持 local 顺序）。 */
+  capabilities: string[]
+}
+
+/** 取交集：结果保持 `local` 的顺序、去重。 */
+export function intersectCapabilities(local: readonly string[], remote: readonly string[]): string[] {
+  const remoteSet = new Set(remote)
+  const seen = new Set<string>()
+  const result: string[] = []
+  for (const cap of local) {
+    if (remoteSet.has(cap) && !seen.has(cap)) {
+      seen.add(cap)
+      result.push(cap)
+    }
+  }
+  return result
+}
+
+/**
+ * 协商。主版本不匹配抛 `E_UNSUPPORTED`（不可重试）——调用方应提示「请升级客户端」。
+ */
+export function negotiate(local: NegotiationInput, remote: NegotiationInput): Negotiated {
+  if (local.protocolVersion !== remote.protocolVersion) {
+    throw new BridgeError(
+      'E_UNSUPPORTED',
+      `protocol version mismatch: local=${local.protocolVersion}, remote=${remote.protocolVersion}`,
+    )
+  }
+  return {
+    protocolVersion: local.protocolVersion,
+    capabilities: intersectCapabilities(local.capabilities, remote.capabilities),
+  }
+}

package/src/protocol/host.ts

@@ -0,0 +1,150 @@
+/**
+ * Host 侧通用胶水（电脑端「接口层」的与传输无关的部分）。
+ *
+ * 设计：**把「方法分发」与「数据来源」解耦**，用 `HostDataSource` 端口隔离。
+ * 于是同一份 bridge 代码有两个数据源实现：
+ *   - 真实：`virlen-app/src/bridge/`，接 `sessionStore` / `chat-service`（含 ACL / 审计）
+ *   - 演示/测试：mock 数据源（`virlen-remote/testing`）
+ * 这样 M2 的浏览器 harness（mock）与 M3 的真实桌面端（真实源）复用同一分发逻辑，
+ * 且 mock 让「不依赖 WebRTC 的端到端联调」成为可能。
+ *
+ * 事件用 `HostEmit` 回填：host 侧（store-bridge / mock）通过它把 `HostEvents` 推给手机。
+ */
+import type { Endpoint } from './endpoint'
+import type {
+  AnswerParams,
+  AnswerResult,
+  CompressParams,
+  ContextInfoDTO,
+  ContextParams,
+  CreateSessionParams,
+  DeleteSessionParams,
+  HostEvents,
+  InteractionDTO,
+  MessageDTO,
+  ModelProviderDTO,
+  MsgPageDTO,
+  MsgPageParams,
+  PinSessionParams,
+  RenameSessionParams,
+  SendParams,
+  SessionSummaryDTO,
+  SetModelParams,
+  WorkspaceOptionDTO,
+} from './api'
+import type { ClientInfo, HelloParams, HelloResult } from './hello'
+
+/** 电脑端接口层的数据来源（返回已投影好的 DTO，投影逻辑在实现侧）。 */
+export interface HostDataSource {
+  listSessions(): SessionSummaryDTO[] | Promise<SessionSummaryDTO[]>
+  getMessages(params: MsgPageParams): MsgPageDTO | Promise<MsgPageDTO>
+  getMessage(params: { sessionId: string; messageId: string }): MessageDTO | Promise<MessageDTO>
+  send(params: SendParams): { messageId: string } | Promise<{ messageId: string }>
+  cancel(params: { sessionId: string }): { ok: true } | Promise<{ ok: true }>
+  /** 从暂停的 run 快照恢复执行（M5，与手机端「暂存」配对）。 */
+  resume(params: { sessionId: string }): { ok: true } | Promise<{ ok: true }>
+  subscribe(params: { sessionId: string; fromRowid?: number }): { ok: true } | Promise<{ ok: true }>
+  answer(params: AnswerParams): AnswerResult | Promise<AnswerResult>
+  /** 当前待应答交互（拉取式；手机每次链路就绪后调一次，补齐错过的 `requested` 事件）。 */
+  listInteractions(): InteractionDTO[] | Promise<InteractionDTO[]>
+  // ── M4 写操作（§16.1）──
+  createSession(params: CreateSessionParams): { sessionId: string } | Promise<{ sessionId: string }>
+  renameSession(params: RenameSessionParams): { ok: true } | Promise<{ ok: true }>
+  setPinned(params: PinSessionParams): { ok: true } | Promise<{ ok: true }>
+  /** ⚠️ 不可逆；实现侧必须校验 `confirm === true`（不得依赖手机 UI）。 */
+  deleteSession(params: DeleteSessionParams): { ok: true } | Promise<{ ok: true }>
+  /** 可选：覆盖默认 hello 应答。 */
+  hello?(params: HelloParams): HelloResult | Promise<HelloResult>
+  // ── §22：模型 / 工作目录 / 上下文 ──
+  /** 已启用的模型服务与模型（白名单：不含 apiKey / baseUrl）。 */
+  listModels(): ModelProviderDTO[] | Promise<ModelProviderDTO[]>
+  /** 切换会话模型；实现侧必须校验「服务已启用且模型存在」。 */
+  setModel(params: SetModelParams): { ok: true } | Promise<{ ok: true }>
+  /** 新建会话可选的工作目录候选集（**只用于新建**，已有会话不可改）。 */
+  listWorkspaces(): WorkspaceOptionDTO[] | Promise<WorkspaceOptionDTO[]>
+  /** 上下文占用快照（口径与桌面 token 环一致）。 */
+  getContext(params: ContextParams): ContextInfoDTO | Promise<ContextInfoDTO>
+  /**
+   * 压缩上下文（fire-and-forget）。
+   *
+   * ⚠️ 实现侧必须校验 `confirm === true`（不得依赖手机 UI），并自行保证「正在回复 / 正在压缩」不被并发触发。
+   */
+  compress(params: CompressParams): { ok: true } | Promise<{ ok: true }>
+}
+
+export type HostEmit = <E extends keyof HostEvents & string>(topic: E, payload: HostEvents[E]) => void
+
+export interface HostRegistration {
+  /** 把一条 `HostEvents` 推给对端（手机）。 */
+  emit: HostEmit
+  /** 注销全部 handler 与订阅。 */
+  dispose(): void
+}
+
+export interface RegisterHostOptions {
+  hostInfo?: ClientInfo
+  /** 本机声明的能力集（会与手机 hello 的能力取交集，见 hello.ts）。 */
+  capabilities?: string[]
+  paired?: boolean
+  deviceName?: string
+}
+
+const DEFAULT_CAPABILITIES = ['session.list', 'session.send', 'interaction.answer', 'stream.delta']
+
+export function registerHostHandlers(
+  endpoint: Endpoint,
+  source: HostDataSource,
+  options: RegisterHostOptions = {},
+): HostRegistration {
+  const disposers: Array<() => void> = []
+
+  const emit: HostEmit = (topic, payload) => {
+    endpoint.emit(topic, payload)
+  }
+
+  const on = (method: string, handler: (params: unknown) => unknown | Promise<unknown>) => {
+    disposers.push(endpoint.handle(method, handler))
+  }
+
+  on('host.hello', async (params) => {
+    if (source.hello) return source.hello(params as HelloParams)
+    const hello = params as Partial<HelloParams>
+    return {
+      protocolVersion: hello.protocolVersion ?? 1,
+      host: options.hostInfo ?? { platform: 'web-harness', appVersion: '0.0.0' },
+      capabilities: options.capabilities ?? DEFAULT_CAPABILITIES,
+      paired: options.paired ?? true,
+      deviceName: options.deviceName ?? 'Virlen 电脑（演示）',
+    } satisfies HelloResult
+  })
+
+  on('host.session.list', async () => ({ sessions: await source.listSessions() }))
+  on('host.session.messages', async (params) => source.getMessages(params as MsgPageParams))
+  on('host.session.message.get', async (params) => {
+    const p = params as { sessionId: string; messageId: string }
+    return { message: await source.getMessage(p) }
+  })
+  on('host.session.send', async (params) => source.send(params as SendParams))
+  on('host.session.cancel', async (params) => source.cancel(params as { sessionId: string }))
+  on('host.session.resume', async (params) => source.resume(params as { sessionId: string }))
+  on('host.session.subscribe', async (params) => source.subscribe(params as { sessionId: string; fromRowid?: number }))
+  on('host.session.create', async (params) => source.createSession(params as CreateSessionParams))
+  on('host.session.rename', async (params) => source.renameSession(params as RenameSessionParams))
+  on('host.session.pin', async (params) => source.setPinned(params as PinSessionParams))
+  on('host.session.delete', async (params) => source.deleteSession(params as DeleteSessionParams))
+  on('host.interaction.answer', async (params) => source.answer(params as AnswerParams))
+  on('host.interaction.list', async () => ({ interactions: await source.listInteractions() }))
+  // ── §22：模型 / 工作目录 / 上下文 ──
+  on('host.model.list', async () => ({ providers: await source.listModels() }))
+  on('host.session.setModel', async (params) => source.setModel(params as SetModelParams))
+  on('host.workspace.list', async () => ({ workspaces: await source.listWorkspaces() }))
+  on('host.session.context', async (params) => source.getContext(params as ContextParams))
+  on('host.session.compress', async (params) => source.compress(params as CompressParams))
+
+  return {
+    emit,
+    dispose() {
+      for (const dispose of disposers) dispose()
+    },
+  }
+}

package/src/protocol/identity.ts

@@ -0,0 +1,184 @@
+/**
+ * 设备身份与授权凭证（M6，见 docs/phone-control-bridge.md §30）。
+ *
+ * 一句话：**设备 key 是「谁」，授权凭证是「凭什么是它」。**
+ *
+ * - **设备 key**：首次运行生成一次，之后**持久化不变**（手机写 localStorage，电脑写
+ *   `<data_dir>/phone-device.json`）。它不是硬件指纹 —— 见 §30.1 的取舍说明：
+ *   PWA 拿不到可靠的硬件指纹（浏览器升级 / 隐私模式 / 清数据即变，同型号还会撞），
+ *   所以唯一能同时满足「不重复」与「重新获取还是同一个」的做法就是随机生成 + 落盘。
+ * - **房间号**由电脑设备 key 派生（`roomFor`）：于是「第二次连接」只需要拿电脑 key 去问
+ *   信令服务「这台电脑在不在线」，不必再扫码。
+ * - **授权凭证**（grant）：由**电脑端**签发，绑定手机设备 key，默认 30 天有效、
+ *   每次成功连接**滑动续期**，但单次签发最长 `GRANT_MAX_LIFETIME_MS`（90 天）——
+ *   到顶后必须重新扫码授权（用户 2026-09-27 拍板）。
+ *
+ * 本模块**零依赖、两端同一份**：电脑端与手机端都必须用这里的常量与判定函数，
+ * 否则必然出现「一端认为有效、另一端认为过期」的分叉（§18.5 的教训）。
+ */
+
+/** 电脑设备 key 前缀（desktop key）。 */
+export const HOST_KEY_PREFIX = 'dk-'
+/** 手机设备 key 前缀（mobile key）。 */
+export const MOBILE_KEY_PREFIX = 'mk-'
+/** 授权凭证前缀（grant）。 */
+export const GRANT_PREFIX = 'gt-'
+
+/** 授权凭证的单次续期时长（30 天）。 */
+export const GRANT_TTL_MS = 30 * 24 * 60 * 60 * 1000
+
+/**
+ * 单次签发的**最长寿命**（90 天，从 `issuedAt` 起算）。
+ *
+ * 为什么要有硬上限：滑动续期若没有上限，一个凭证就等于永久授权 —— 手机丢失/被借用时
+ * 电脑端的「移除」是唯一刹车，而用户未必想得起来去看那张列表。
+ */
+export const GRANT_MAX_LIFETIME_MS = 90 * 24 * 60 * 60 * 1000
+
+/** 房间名前缀（信令层）。与 M3 起的旧房间名同构：`virlen:<电脑标识>`。 */
+export const ROOM_PREFIX = 'virlen:'
+
+export type DeviceKind = 'host' | 'mobile'
+
+/**
+ * 一条授权凭证（电脑侧是**真源**，手机侧存副本）。
+ *
+ * `token` 在续期时**保持不变**（只推后 `expiresAt`）—— 凭证字符串是「这次配对」的身份，
+ * 每次连接都换新串会让重连路径（内存里的 `lastOptions` / 本地存储的写入时序）出现
+ * 「用旧串连、被判无效」的窗口。要换串只有一种场景：**重新扫码**（新签发）。
+ */
+export interface GrantRecord {
+  token: string
+  /** 首次签发时刻（硬上限 `GRANT_MAX_LIFETIME_MS` 据此起算）。 */
+  issuedAt: number
+  /** 当前到期时刻（滑动续期会推后，但不超过 `issuedAt + 硬上限`）。 */
+  expiresAt: number
+  /** 最近一次成功连接时刻（电脑端列表展示用）。 */
+  lastSeenAt?: number
+}
+
+/** 凭证被拒的原因（线上随 `E_DENIED` 的 `data.reason` 回传，手机据此给不同文案）。 */
+export type CredentialRejectReason = 'invalid' | 'expired' | 'revoked'
+
+/** 房间在线状态（信令服务 `POST /status` 的应答元素）。 */
+export interface RoomStatus {
+  room: string
+  /** 电脑端是否在线（有 host 角色的活跃连接）。 */
+  hostOnline: boolean
+  /** 是否已有手机占着 guest 位（第二台手机会顶掉它，见 §30.3）。 */
+  guestOnline: boolean
+  /** host / guest 的加入时刻（毫秒；不在线则缺省）。 */
+  hostSince?: number
+  guestSince?: number
+}
+
+/** 生成 `prefix + 十六进制随机串`（默认 16 字节 = 32 hex）。 */
+export function randomKey(prefix: string, bytes = 16): string {
+  const buf = new Uint8Array(bytes)
+  const c = (globalThis as { crypto?: Crypto }).crypto
+  if (c && typeof c.getRandomValues === 'function') {
+    c.getRandomValues(buf)
+  } else {
+    // 无 WebCrypto 的环境（老 Node / 极端降级）：Math.random 兜底。
+    // ⚠️ 只用于「本地身份标识」，不是加密码 —— 真正的安全边界是授权凭证与电脑端确认弹窗。
+    for (let i = 0; i < buf.length; i += 1) buf[i] = Math.floor(Math.random() * 256)
+  }
+  let out = prefix
+  for (const b of buf) out += b.toString(16).padStart(2, '0')
+  return out
+}
+
+/** 生成一个设备 key（`host` → `dk-…`，`mobile` → `mk-…`）。 */
+export function newDeviceKey(kind: DeviceKind): string {
+  return randomKey(kind === 'host' ? HOST_KEY_PREFIX : MOBILE_KEY_PREFIX)
+}
+
+/** 生成一个授权凭证串。 */
+export function newGrantToken(): string {
+  return randomKey(GRANT_PREFIX, 24)
+}
+
+const KEY_RE = /^(dk|mk)-[0-9a-f]{8,64}$/
+
+/**
+ * 是否为合法设备 key。`kind` 不传则不校验前缀归属。
+ *
+ * 只用于**早期拒掉明显是垃圾的输入**（日志可读、列表可渲染），不是安全校验 ——
+ * 真正的授权判定在电脑端的凭证表。
+ */
+export function isDeviceKey(value: unknown, kind?: DeviceKind): value is string {
+  if (typeof value !== 'string' || !KEY_RE.test(value)) return false
+  if (!kind) return true
+  return value.startsWith(kind === 'host' ? HOST_KEY_PREFIX : MOBILE_KEY_PREFIX)
+}
+
+/**
+ * 电脑设备 key → 信令房间号。
+ *
+ * ⚠️ 兼容 M3 的旧房间名：旧 `hostId`（如 `host-ab12cd34`，无前缀）传进来同样得到
+ * `virlen:host-ab12cd34` —— 与旧实现逐字一致，于是**旧二维码仍然可用**（§30.6）。
+ */
+export function roomFor(hostKey: string): string {
+  return ROOM_PREFIX + hostKey
+}
+
+/** 房间号 → 电脑设备 key（非本前缀派生时返回 `null`）。 */
+export function hostKeyFromRoom(room: string): string | null {
+  if (typeof room !== 'string' || !room.startsWith(ROOM_PREFIX)) return null
+  const key = room.slice(ROOM_PREFIX.length)
+  return key ? key : null
+}
+
+/** 签发一条新凭证（`now` 可注入，便于测试）。 */
+export function issueGrant(now: number = Date.now()): GrantRecord {
+  return {
+    token: newGrantToken(),
+    issuedAt: now,
+    expiresAt: now + GRANT_TTL_MS,
+    lastSeenAt: now,
+  }
+}
+
+/** 凭证是否已过期。 */
+export function isGrantExpired(grant: GrantRecord, now: number = Date.now()): boolean {
+  return now >= grant.expiresAt
+}
+
+/**
+ * 滑动续期：把到期时间推后到 `now + 30 天`，但**不超过** `issuedAt + 90 天`。
+ *
+ * 返回新对象（不原地改），调用方负责持久化 —— 「算」与「存」分开，便于测试与审计。
+ */
+export function renewGrant(grant: GrantRecord, now: number = Date.now()): GrantRecord {
+  const cap = grant.issuedAt + GRANT_MAX_LIFETIME_MS
+  return {
+    ...grant,
+    expiresAt: Math.min(now + GRANT_TTL_MS, cap),
+    lastSeenAt: now,
+  }
+}
+
+/**
+ * 凭证可用性判定（**两端共用**）。
+ * 返回 `null` = 可用；否则是拒绝原因。
+ */
+export function checkGrant(
+  grant: GrantRecord | null | undefined,
+  now: number = Date.now(),
+): CredentialRejectReason | null {
+  if (!grant || typeof grant.token !== 'string' || !grant.token) return 'invalid'
+  if (isGrantExpired(grant, now)) return 'expired'
+  return null
+}
+
+/** 剩余有效期的自然语言（两端 UI 共用同一套口径，避免「还剩 3 天」与「2.9 天」打架）。 */
+export function describeGrantRemaining(grant: { expiresAt: number }, now: number = Date.now()): string {
+  const left = grant.expiresAt - now
+  if (left <= 0) return '已过期'
+  const days = Math.floor(left / (24 * 60 * 60 * 1000))
+  if (days >= 1) return `剩余 ${days} 天`
+  const hours = Math.floor(left / (60 * 60 * 1000))
+  if (hours >= 1) return `剩余 ${hours} 小时`
+  const minutes = Math.max(1, Math.floor(left / 60000))
+  return `剩余 ${minutes} 分钟`
+}

package/src/protocol/ids.ts

@@ -0,0 +1,20 @@
+/**
+ * requestId 生成 —— 零依赖。
+ *
+ * 用于 RPC 幂等（见 docs/phone-control-bridge.md §3.2）：手机网络会闪断，重连后必然重发，
+ * 电脑侧靠 requestId 去重、**返回上次结果而非重放**。
+ *
+ * 优先用 `crypto.randomUUID()`（浏览器安全上下文 / Node ≥ 19 均可用）；
+ * 退化为「时间戳 + 单调计数 + 随机」——**不用于安全用途**，仅需高概率唯一。
+ */
+let fallbackCounter = 0
+
+export function newRequestId(): string {
+  const c = (globalThis as { crypto?: Crypto }).crypto
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID()
+  }
+  fallbackCounter = (fallbackCounter + 1) >>> 0
+  const rand = Math.random().toString(36).slice(2, 10)
+  return `${Date.now().toString(36)}-${fallbackCounter.toString(36)}-${rand}`
+}

package/src/protocol/pairing.ts

@@ -0,0 +1,95 @@
+/**
+ * 配对载荷（二维码 / 配对串的内容）—— **两端同一份**（M6，见 docs/phone-control-bridge.md §30.2）。
+ *
+ * 为什么搬到共享包：此前电脑端 `pairingPayload()` 与手机端 `parsePayload()` 各写一份 interface，
+ * 字段含义靠注释对齐 —— 这类「契约写两份」的分叉只会在真机上暴露（§26/§29 都是这个形状的缺陷）。
+ *
+ * 字段：
+ * - `host`：**电脑设备 key**（`dk-…`；M3 的旧码是 `host-…`，同样能解析）。
+ * - `ticket`：**一次性**配对票据（不是长期凭证！兑换后电脑端签发 `grant` 回传，见 §30.3）。
+ * - `signal`：信令基址；缺省 = 同源 Broadcast 联调（生产必有）。
+ * - `room`：信令房间号；**缺省由 `roomFor(host)` 派生**。保留字段只为兼容旧码。
+ */
+import { roomFor } from './identity'
+
+/** 当前载荷版本。v1 与 v2 形状相同（差异在语义：v2 起 `host` 是设备 key、`ticket` 是一次性票据）。 */
+export const PAIRING_PAYLOAD_VERSION = 2
+
+/**
+ * 配对票据有效期（默认 5 分钟）。
+ *
+ * 用户反馈「扫码后提示二维码失效」时的值曾是 2 分钟；现在 **5 分钟 + 面板打开即重生成 +
+ * 到期自动重生成**（见 `phoneControlStore`）三管齐下，真机上基本不可能再扫到过期码。
+ */
+export const PAIRING_TICKET_TTL_MS = 5 * 60 * 1000
+
+export interface PairingPayload {
+  v: number
+  /** 电脑设备 key（也是房间号的来源）。 */
+  host: string
+  /** 电脑显示名（手机列表里显示）。 */
+  name: string
+  /** 一次性配对票据。 */
+  ticket: string
+  /** 信令基址（如 `https://virlen.cn/api/rtc/`）。 */
+  signal?: string
+  /** 信令房间号（缺省 `roomFor(host)`；旧码里带着它）。 */
+  room?: string
+}
+
+/** 构造载荷（只填必要字段；`room` 交给两端各自派生，避免又多一处可漂移的冗余）。 */
+export function buildPairingPayload(input: {
+  host: string
+  name: string
+  ticket: string
+  signal?: string
+}): PairingPayload {
+  return {
+    v: PAIRING_PAYLOAD_VERSION,
+    host: input.host,
+    name: input.name,
+    ticket: input.ticket,
+    ...(input.signal ? { signal: input.signal } : {}),
+  }
+}
+
+/** 序列化为二维码内容。 */
+export function encodePairingPayload(payload: PairingPayload): string {
+  return JSON.stringify(payload)
+}
+
+/**
+ * 解析二维码 / 配对串。无法识别返回 `null`（调用方给「不是 Virlen 配对码」的文案）。
+ *
+ * 宽容点（都是真机上会遇到的东西）：
+ * - `v` 缺省按 1 处理（旧码）；
+ * - `name` 缺省回退 `host`；
+ * - `ticket` 允许是任意非空串（前缀只作可读性，不作校验 —— 电脑端的判定才是权威）。
+ */
+export function parsePairingPayload(text: string): PairingPayload | null {
+  if (typeof text !== 'string' || !text.trim()) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as Partial<PairingPayload>
+  if (typeof obj.host !== 'string' || !obj.host.trim()) return null
+  if (typeof obj.ticket !== 'string' || !obj.ticket.trim()) return null
+  const payload: PairingPayload = {
+    v: typeof obj.v === 'number' ? obj.v : 1,
+    host: obj.host.trim(),
+    name: typeof obj.name === 'string' && obj.name.trim() ? obj.name.trim() : obj.host.trim(),
+    ticket: obj.ticket.trim(),
+  }
+  if (typeof obj.signal === 'string' && obj.signal.trim()) payload.signal = obj.signal.trim()
+  if (typeof obj.room === 'string' && obj.room.trim()) payload.room = obj.room.trim()
+  return payload
+}
+
+/** 载荷 → 房间号（显式 `room` 优先，否则由电脑 key 派生）。 */
+export function roomOfPayload(payload: PairingPayload): string {
+  return payload.room ?? roomFor(payload.host)
+}

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+/**
+ * `virlen-remote/testing` —— 测试/演示专用的宿主实现（**不进生产包**）。
+ */
+export { createMockHostDataSource } from './mock-host'
+export type { MockHostDataSource, MockHostOptions, MockInteractionSpec } from './mock-host'