virlen-remote 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 变更记录
+
+本文件记录对外可见的变更（协议 / 导出面 / 行为）。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [0.1.0] - 2026-09-30
+
+首次发布。内容为 Virlen「手机控制」M0–M6 期间沉淀的协议栈，两端（virlen-app / virlen-mobile）此前以源码方式共用，
+本版起改为从 npm 安装。
+
+### Added
+
+- **协议层**：帧编解码 / 分片重组（`encodeFrames` / `Reassembler`）、RPC 端点（`Endpoint`：幂等、超时、重放）、
+  错误码（`BridgeError` / `toBridgeError`）、能力协商（`negotiate` / `intersectCapabilities`）、
+  方法表与 DTO（`createCaller` / `createSubscriber` / `registerHostHandlers`、`HostApi` / `MobileApi`）。
+- **设备身份与授权凭证**：`newDeviceKey` / `roomFor` / `issueGrant` / `renewGrant` / `checkGrant` /
+  `describeGrantRemaining`（30 天滑动续期 + 90 天硬上限）。
+- **配对载荷**：`buildPairingPayload` / `encodePairingPayload` / `parsePairingPayload` / `roomOfPayload`
+  （二维码内容，两端同一份；票据默认 5 分钟有效）。
+- **传输层**：`Transport` 抽象；`RtcTransport`（WebRTC DataChannel，含被顶号 `E_REPLACED` 语义）、
+  `MemoryTransport` / `createMemoryPair`（测试）、`BroadcastTransport`（同源跨 tab 联调）；
+  `SseSignalingClient`（角色化加入、顶号通知、`requireHostOnline`）、
+  `fetchRoomStatus` / `fetchHostOnlineMap`（批量在线查询，失败返回空而不抛错）。
+- **流式下行**：`host.event.message.stream` 支持 `mode: 'full' | 'delta'` —— 客户端在 `hello` 里
+  声明 `streamMode: 'delta'` 后只发新增后缀（带 `offset` 供重基准与缺口对齐）：
+  一条 n 字回复的下行带宽从 O(n²) 降到 O(n)；未声明的客户端继续收整帧。
+- **ICE 配置**：`resolveIceServers` / `fetchIceServers` / `sanitizeIceServers` / `parseIceText` /
+  `readCustomIceText` / `writeCustomIceText` —— 客户端**不含任何 TURN 凭证**，
+  默认值由服务端 `GET <信令基址>/ice` 下发，本地缓存 + 多级降级。
+- **测试辅助**（子路径 `virlen-remote/testing`）：`createMockHostDataSource()`。
+
+### Notes
+
+- **ESM only**，零运行时依赖，Node ≥ 18。
+- 构建产物会补全相对导入的 `.js` 后缀（运行时 ESM 加载器要求），见 `scripts/build.mjs`。
+- 对外类型不用 DOM 类型做契约（ICE 条目为 `IceServerInit`），避免要求消费方开启 DOM lib。
+- 若消费方 tsconfig 关闭了 `strictNullChecks`，判别字段请用 `x.ok === false` 显式比较：
+  真值判断不收敛联合类型。
+
+[0.1.0]: https://github.com/WeiChens/virlen-remote/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WeiChens
+
+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

@@ -0,0 +1,192 @@
+# virlen-remote
+
+Virlen「手机控制电脑」功能的**协议栈共享包** —— 电脑端（virlen-app）与手机端（virlen-mobile）
+共用同一份实现，避免两端各写一份契约然后慢慢漂移。
+
+- **零运行时依赖**：WebRTC 用浏览器原生 `RTCPeerConnection`，信令用 `fetch` + `EventSource`，
+  Node 侧只用内存传输做测试。
+- **ESM only**（`"type": "module"`）：Node ≥ 18，或任意现代打包器（Vite / webpack / esbuild / Rollup）。
+- 自带类型声明（`.d.ts` + `.d.ts.map`，随包附源码便于跳转）。
+- **源码与产物里都没有任何 TURN 凭证** —— ICE 默认值由服务端下发，见下文。
+
+## 安装
+
+```bash
+npm i virlen-remote
+# 或 pnpm add virlen-remote / yarn add virlen-remote
+```
+
+```ts
+import { Endpoint, RtcTransport } from 'virlen-remote'
+import { createMockHostDataSource } from 'virlen-remote/testing'   // 仅测试/联调用
+```
+
+## 它包含什么
+
+| 分层 | 内容 |
+|---|---|
+| `protocol/` | 帧编解码与分片重组、RPC（`Endpoint` / 幂等 / 超时 / 重放）、错误码、能力协商、方法表与 DTO、设备身份与授权凭证、配对载荷、流式下行（整帧 / 增量） |
+| `transport/` | `Transport` 抽象 + 三种实现（`RtcTransport` / `MemoryTransport` / `BroadcastTransport`）、`SseSignalingClient`（信令）、ICE 配置解析 |
+| `testing/`（子路径） | `createMockHostDataSource()`：可直接挂到 `registerHostHandlers` 的 mock 宿主，供两端联调与单测使用 |
+
+## 快速开始
+
+### 电脑端（host，发起 offer）
+
+```ts
+import {
+  Endpoint,
+  RtcTransport,
+  SseSignalingClient,
+  registerHostHandlers,
+  newDeviceKey,
+  roomFor,
+  resolveIceServers,
+} from 'virlen-remote'
+
+// 设备 key 首次生成后**必须持久化**：它既是「这台电脑是谁」，也是房间号的来源
+const deviceKey = newDeviceKey('host')
+const signalUrl = 'https://your-server/api/rtc/'
+const room = roomFor(deviceKey)
+
+// ICE 默认值从信令服务取（服务端配置；本机可自定义覆盖）
+const ice = await resolveIceServers({ baseUrl: signalUrl, storage: localStorage })
+
+const signaling = new SseSignalingClient({
+  baseUrl: signalUrl,
+  room,
+  role: 'host',
+  deviceKey,
+  clientName: '我的电脑',
+})
+const transport = new RtcTransport({ role: 'host', signaling, iceServers: ice.servers })
+const endpoint = new Endpoint({ transport })
+
+registerHostHandlers(endpoint, myDataSource) // 实现 HostDataSource 端口即可
+void transport.start()
+```
+
+### 手机端（guest，应答方）
+
+```ts
+import {
+  Endpoint,
+  RtcTransport,
+  SseSignalingClient,
+  createCaller,
+  type HostApi,
+} from 'virlen-remote'
+
+const signaling = new SseSignalingClient({
+  baseUrl: signalUrl,
+  room,                       // 与电脑端同一个房间（由电脑 key 派生）
+  role: 'guest',
+  deviceKey: mobileKey,
+  requireHostOnline: true,    // 房间里没有电脑时立刻失败，而不是空等超时
+})
+const transport = new RtcTransport({ role: 'guest', signaling, iceServers: ice.servers })
+await transport.start()
+await transport.whenReady()
+
+const caller = createCaller<HostApi>(new Endpoint({ transport }))
+const hello = await caller.call('host.hello', {
+  protocolVersion: 1,
+  client: { platform: 'ios-web', appVersion: '0.1.0' },
+  capabilities: ['session.list', 'session.send'],
+  token, // 首次配对是一次性票据；之后是上一轮拿到的授权凭证
+  mobileKey,
+  mobileName: 'iPhone · 3f9a',
+})
+// 首次配对就在这里拿到长期凭证：
+// hello.grant → { token: 'gt-…', issuedAt, expiresAt }
+```
+
+### 配对（二维码 / 配对串）
+
+```ts
+import {
+  buildPairingPayload,
+  encodePairingPayload,
+  parsePairingPayload,
+  roomOfPayload,
+} from 'virlen-remote'
+
+const payload = buildPairingPayload({ host: deviceKey, name: '我的电脑', ticket, signal: signalUrl })
+const qrText = encodePairingPayload(payload)     // 画进二维码
+const back = parsePairingPayload(qrText)         // 手机端解析（无法识别时返回 null）
+if (back) await connect(roomOfPayload(back), back.host, back.ticket)
+```
+
+## ICE / TURN 配置
+
+**本包与两个客户端里都没有任何 TURN 凭证。** 默认值由**服务端**提供：
+
+```
+GET <信令基址>/ice
+→ { "v": 1,
+    "iceServers": [ { "urls": "stun:turn.example.com:3478" },
+                    { "urls": "turn:turn.example.com:3478", "username": "…", "credential": "…" } ],
+    "mode": "static" | "rest" | "none",
+    "ttlSec": 3600, "expiresAt": 1730000000000 }
+```
+
+客户端用 `resolveIceServers()` 解析，优先级与降级：
+
+```
+自定义（用户手填）
+  > 服务端下发的本地缓存（默认 6 小时）
+    > 服务端现取
+      > 过期缓存（信令暂时不可达时，旧的也比没有强）
+        > 空（仅本机候选；局域网可用，跨网多半不行）
+```
+
+```ts
+import { resolveIceServers } from 'virlen-remote'
+
+const ice = await resolveIceServers({
+  baseUrl: signalUrl,
+  customText: localStorage.getItem('virlen.rtc.ice'), // 用户自定义（空 = 用服务端默认）
+  storage: localStorage,                              // 缓存位置
+})
+ice.servers   // → 交给 new RTCPeerConnection({ iceServers })
+ice.source    // → 'custom' | 'remote' | 'cache' | 'stale-cache' | 'none'
+ice.detail    // → 给用户看的中文说明（两端同一套口径）
+ice.warning   // → 降级原因（如「信令服务暂不可达，先用上次缓存」）
+```
+
+要点：
+
+- **永不抛错**：任何一步失败都降级到下一优先级，并把来源如实报给上层 ——
+  「拿不到 TURN 配置」不该让用户连不上，只该让跨网连通率变差；
+- 服务端可配**静态口令**，也可用 coturn `use-auth-secret` 下发**临时凭证**
+  （HMAC-SHA1 现算，密钥永不下发；被抄走也只有一小时额度）；
+- 凭证会随 `iceServers` 一起进内存，因此**不要**把它写进日志或埋点
+  （本包提供 `iceCount` / `iceSource` 这类只记元数据的写法）。
+
+## 约定与边界
+
+- **不用 DOM 类型做对外契约**：例如 ICE 条目是结构等价的 `IceServerInit`
+  而非 DOM 的 `RTCIceServer`，避免把「需要 DOM lib」扩散到所有消费方；
+- `Transport.onError?()` 是**可选**方法：只有 `RtcTransport` 有致命错误通道（如被顶号 `E_REPLACED`）；
+- **布尔判别字段请显式比较**（`x.ok === false` 而不是 `!x.ok`）：若消费方 tsconfig 关了
+  `strictNullChecks`，真值判断不收敛联合类型；
+- **被顶号不要自动重连**：信令服务是「后来者优先」，自动重连会让两台设备互相顶号；
+- 房间号由电脑设备 key 派生（`roomFor`）：**知道 key 就能进房间**，授权关口是凭证校验。
+
+## 维护者：构建与发布
+
+```bash
+pnpm install
+pnpm typecheck && pnpm test    # 类型检查 + 用例
+pnpm build                     # 产出 dist/（ESM + .d.ts）
+npm publish                    # prepublishOnly 会自动跑上面三步
+```
+
+`pnpm build` 在 `tsc` 之后会把产物里的**相对导入补上 `.js` 后缀**：
+源码里的免后缀写法对打包器友好，但**运行时 ESM 加载器不认**（`./protocol/frame` 会 404）。
+本包是被 `import` 直接消费的，所以产物必须是合法 ESM。实现见 `scripts/build.mjs`
+（零新增依赖，逐文件可 diff）。
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * virlen-remote —— 手机控制协议栈共享包
+ *
+ * 电脑端（virlen-app）与手机端（virlen-mobile）共用同一份实现
+ * （见 docs/phone-control-bridge.md §1「越往下越同构」、§6「共享包」）。
+ *
+ * 分层：
+ *   protocol/   与传输无关的逻辑（帧 / RPC / 错误 / 能力协商 / 方法表）
+ *   transport/  字节通道抽象 + 内存实现（RTC 实现属 M3）
+ *
+ * **零运行时依赖**：WebRTC 用浏览器原生 `RTCPeerConnection`；Node 侧只用 memory transport 做测试。
+ */
+export { PROTOCOL_VERSION, HEADER_SIZE, DEFAULT_MAX_FRAME_PAYLOAD, FrameKind } from './protocol/frame.js';
+export { encodeHeader, decodeHeader, frameBody, encodeFrames, Reassembler } from './protocol/frame.js';
+export type { FrameHeader, DecodedMessage } from './protocol/frame.js';
+export { BridgeError, toBridgeError } from './protocol/errors.js';
+export type { ErrorCode, WireError, BridgeErrorOptions } from './protocol/errors.js';
+export { newRequestId } from './protocol/ids.js';
+export { HOST_KEY_PREFIX, MOBILE_KEY_PREFIX, GRANT_PREFIX, ROOM_PREFIX, GRANT_TTL_MS, GRANT_MAX_LIFETIME_MS, randomKey, newDeviceKey, newGrantToken, isDeviceKey, roomFor, hostKeyFromRoom, issueGrant, isGrantExpired, renewGrant, checkGrant, describeGrantRemaining, } from './protocol/identity.js';
+export type { DeviceKind, GrantRecord, CredentialRejectReason, RoomStatus } from './protocol/identity.js';
+export { PAIRING_PAYLOAD_VERSION, PAIRING_TICKET_TTL_MS, buildPairingPayload, encodePairingPayload, parsePairingPayload, roomOfPayload, } from './protocol/pairing.js';
+export type { PairingPayload } from './protocol/pairing.js';
+export { normalizeChoiceAnswer, answerActionError, CHOICE_JOINER } from './protocol/answer.js';
+export type { ChoiceAnswer } from './protocol/answer.js';
+export { negotiate, intersectCapabilities } from './protocol/hello.js';
+export { Endpoint } from './protocol/endpoint.js';
+export type { CallContext, EventContext, RpcHandler, EventSubscriber, CallOptions, EndpointOptions, } from './protocol/endpoint.js';
+export { createCaller, createSubscriber, registerHandlers } from './protocol/api.js';
+export { DEFAULT_CONTEXT_WINDOW_TOKENS, COMPRESS_MIN_RATIO } from './protocol/api.js';
+export type { ParamsOf, ResultOf, TypedCaller, TypedSubscriber, HandlerImpl, HostApi, MobileApi, HostEvents, MobileEvents, SessionSummaryDTO, MessageDTO, RuntimeDTO, InteractionDTO, InteractionOutcome, StreamMode, ApprovalTier, SendParams, MsgPageParams, MsgPageDTO, AnswerParams, AnswerAction, AnswerResult, AnswerRejectReason, CreateSessionParams, RenameSessionParams, PinSessionParams, DeleteSessionParams, ModelProviderDTO, WorkspaceOptionDTO, ContextInfoDTO, SetModelParams, ContextParams, CompressParams, } from './protocol/api.js';
+export type { HelloParams, HelloResult, ClientInfo, NegotiationInput, Negotiated } from './protocol/hello.js';
+export { registerHostHandlers } from './protocol/host.js';
+export type { HostDataSource, HostEmit, HostRegistration, RegisterHostOptions } from './protocol/host.js';
+export type { Transport, TransportState } from './transport/types.js';
+export { MemoryTransport, createMemoryPair } from './transport/memory.js';
+export type { MemoryTransportMetrics } from './transport/memory.js';
+export { BroadcastTransport, createBroadcastPair } from './transport/broadcast.js';
+export { SseSignalingClient, fetchRoomStatus, fetchHostOnlineMap } from './transport/signaling.js';
+export type { SignalingChannel, SignalingRole, SseSignalingOptions, EventSourceLike, KickedInfo, FetchRoomStatusOptions, } from './transport/signaling.js';
+export { RtcTransport } from './transport/rtc.js';
+export type { RtcTransportOptions } from './transport/rtc.js';
+export { ICE_CONFIG_VERSION, ICE_API_PATH, ICE_CUSTOM_STORAGE_KEY, ICE_REMOTE_STORAGE_KEY, ICE_CACHE_TTL_MS, ICE_FETCH_TIMEOUT_MS, sanitizeIceServers, parseIceText, formatIceServers, describeIceSource, fetchIceServers, resolveIceServers, readCustomIceText, writeCustomIceText, } from './transport/ice.js';
+export type { IceServerInit, IceSource, IceStoragePort, ResolvedIceServers, ParseIceResult, FetchIceOptions, ResolveIceOptions, } from './transport/ice.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * virlen-remote —— 手机控制协议栈共享包
+ *
+ * 电脑端（virlen-app）与手机端（virlen-mobile）共用同一份实现
+ * （见 docs/phone-control-bridge.md §1「越往下越同构」、§6「共享包」）。
+ *
+ * 分层：
+ *   protocol/   与传输无关的逻辑（帧 / RPC / 错误 / 能力协商 / 方法表）
+ *   transport/  字节通道抽象 + 内存实现（RTC 实现属 M3）
+ *
+ * **零运行时依赖**：WebRTC 用浏览器原生 `RTCPeerConnection`；Node 侧只用 memory transport 做测试。
+ */
+// ── protocol ──
+export { PROTOCOL_VERSION, HEADER_SIZE, DEFAULT_MAX_FRAME_PAYLOAD, FrameKind } from './protocol/frame.js';
+export { encodeHeader, decodeHeader, frameBody, encodeFrames, Reassembler } from './protocol/frame.js';
+export { BridgeError, toBridgeError } from './protocol/errors.js';
+export { newRequestId } from './protocol/ids.js';
+// ── 设备身份与授权凭证（M6，§30）──
+export { HOST_KEY_PREFIX, MOBILE_KEY_PREFIX, GRANT_PREFIX, ROOM_PREFIX, GRANT_TTL_MS, GRANT_MAX_LIFETIME_MS, randomKey, newDeviceKey, newGrantToken, isDeviceKey, roomFor, hostKeyFromRoom, issueGrant, isGrantExpired, renewGrant, checkGrant, describeGrantRemaining, } from './protocol/identity.js';
+// ── 配对载荷（二维码内容，两端同一份）──
+export { PAIRING_PAYLOAD_VERSION, PAIRING_TICKET_TTL_MS, buildPairingPayload, encodePairingPayload, parsePairingPayload, roomOfPayload, } from './protocol/pairing.js';
+export { normalizeChoiceAnswer, answerActionError, CHOICE_JOINER } from './protocol/answer.js';
+export { negotiate, intersectCapabilities } from './protocol/hello.js';
+export { Endpoint } from './protocol/endpoint.js';
+export { createCaller, createSubscriber, registerHandlers } from './protocol/api.js';
+export { DEFAULT_CONTEXT_WINDOW_TOKENS, COMPRESS_MIN_RATIO } from './protocol/api.js';
+export { registerHostHandlers } from './protocol/host.js';
+export { MemoryTransport, createMemoryPair } from './transport/memory.js';
+export { BroadcastTransport, createBroadcastPair } from './transport/broadcast.js';
+export { SseSignalingClient, fetchRoomStatus, fetchHostOnlineMap } from './transport/signaling.js';
+export { RtcTransport } from './transport/rtc.js';
+// ── ICE 配置（M7，§31）：客户端不再内置任何 TURN 凭证 ──
+export { ICE_CONFIG_VERSION, ICE_API_PATH, ICE_CUSTOM_STORAGE_KEY, ICE_REMOTE_STORAGE_KEY, ICE_CACHE_TTL_MS, ICE_FETCH_TIMEOUT_MS, sanitizeIceServers, parseIceText, formatIceServers, describeIceSource, fetchIceServers, resolveIceServers, readCustomIceText, writeCustomIceText, } from './transport/ice.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,yBAAyB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACtG,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAGnG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C,yBAAyB;AACzB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,SAAS,EACT,YAAY,EACZ,aAAa,EACb,WAAW,EACX,OAAO,EACP,eAAe,EACf,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,sBAAsB,GACvB,MAAM,qBAAqB,CAAA;AAG5B,yBAAyB;AACzB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAG3F,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAU9C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjF,OAAO,EAAE,6BAA6B,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAsClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAItD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAEtE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC/E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAS/F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,yCAAyC;AACzC,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,iBAAiB,CAAA"}

package/dist/protocol/answer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 应答载荷的规范化 —— **手机侧与电脑侧共用同一份**（M4）。
+ *
+ * 为什么必须共用：手机回答「AI 提问」时，最终要交给引擎的是一个 `ToolResult`
+ * （`{ content, uiData }`），而电脑侧 UI 早就定下了这个形态（见 `tool-ui.tsx`）：
+ * `content` = `[selected.join(', '), customReply].filter(Boolean).join('；')`。
+ *
+ * 如果手机侧、电脑侧桥接层、mock 宿主各写一份「怎么拼」，三份必然漂移
+ * —— 而漂移的表现是「AI 收到了内容，但消息渲染不出来（`uiData` 缺失）」这种**看不出错在谁**的故障。
+ * 故：**唯一实现放这里**，其余全部调用它。
+ *
+ * 手机端允许三种输入（宽容解析，避免因 UI 形态变化而连带改协议）：
+ * - 字符串 → 等价于「自定义回复」；
+ * - 字符串数组 → 等价于「选中了这些选项」；
+ * - 对象 `{ selected?, customReply? }` → 精确形态（推荐）。
+ *
+ * 空结果一律返回 `null`（调用方据此回 `invalid-value`）——
+ * 给引擎发一条空回执会让 AI 无从判断用户到底选了什么。
+ */
+import type { AnswerAction, AnswerRejectReason, InteractionDTO } from './api.js';
+export interface ChoiceAnswer {
+    content: string;
+    uiData: {
+        selected: string[];
+        customReply: string;
+    };
+}
+/** 分隔符：与电脑侧 UI 的 `t('；')` 一致（中文分号）。 */
+export declare const CHOICE_JOINER = "\uFF1B";
+export declare function normalizeChoiceAnswer(value: unknown): ChoiceAnswer | null;
+/**
+ * 应答动作的**合法性校验** —— 真实电脑侧（`interaction-registry`）与 mock 宿主共用同一份。
+ *
+ * 为什么放在共享包（M4 教训延续，2026-09-27 真机反馈）：动作「对某类交互是否合法」是**协议语义**，
+ * 不是某一端的实现细节。两端各写一份时 mock 会偏宽松 ——
+ * 「手机对 AI 提问点取消 → 真实电脑端回 `unsupported-by-host`」这类缺陷在手机端单测里测不出来，
+ * 只能等到真机才暴露。
+ *
+ * 判据（与桌面 `tool-ui.tsx` 的按钮一一对应）：
+ * - `choice`（AI 提问）：`choose` 确认 / `deny` 取消 / `shelve` 暂存；`allow` 无意义；
+ * - `authorization`（授权）：`allow` / `deny` / `shelve`；`choose` 无意义；
+ * - `authorization + presentation: 'terminal'`（终端内确认）：**没有暂存语义**
+ *   （它是「命令已就绪，等你按回车」，没有可暂存的对象）。
+ *
+ * @returns 不合法时返回拒绝原因（固定 `unsupported-by-host`）；合法时返回 `null`。
+ */
+export declare function answerActionError(interaction: Pick<InteractionDTO, 'kind' | 'presentation'>, action: AnswerAction): AnswerRejectReason | null;
+//# sourceMappingURL=answer.d.ts.map

package/dist/protocol/answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/protocol/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAE7E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACpD;AAED,uCAAuC;AACvC,eAAO,MAAM,aAAa,WAAM,CAAA;AAEhC,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CA6BzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,cAAc,CAAC,EAC1D,MAAM,EAAE,YAAY,GACnB,kBAAkB,GAAG,IAAI,CAS3B"}

package/dist/protocol/answer.js

@@ -0,0 +1,65 @@
+/** 分隔符：与电脑侧 UI 的 `t('；')` 一致（中文分号）。 */
+export const CHOICE_JOINER = '；';
+export function normalizeChoiceAnswer(value) {
+    let selected = [];
+    let customReply = '';
+    if (typeof value === 'string') {
+        customReply = value.trim();
+    }
+    else if (Array.isArray(value)) {
+        selected = value
+            .filter((v) => typeof v === 'string')
+            .map((v) => v.trim())
+            .filter(Boolean);
+    }
+    else if (value && typeof value === 'object') {
+        const v = value;
+        if (Array.isArray(v.selected)) {
+            selected = v.selected
+                .filter((x) => typeof x === 'string')
+                .map((x) => x.trim())
+                .filter(Boolean);
+        }
+        if (typeof v.customReply === 'string')
+            customReply = v.customReply.trim();
+    }
+    else {
+        return null;
+    }
+    if (!selected.length && !customReply)
+        return null;
+    const parts = [];
+    if (selected.length)
+        parts.push(selected.join(', '));
+    if (customReply)
+        parts.push(customReply);
+    return { content: parts.join(CHOICE_JOINER), uiData: { selected, customReply } };
+}
+/**
+ * 应答动作的**合法性校验** —— 真实电脑侧（`interaction-registry`）与 mock 宿主共用同一份。
+ *
+ * 为什么放在共享包（M4 教训延续，2026-09-27 真机反馈）：动作「对某类交互是否合法」是**协议语义**，
+ * 不是某一端的实现细节。两端各写一份时 mock 会偏宽松 ——
+ * 「手机对 AI 提问点取消 → 真实电脑端回 `unsupported-by-host`」这类缺陷在手机端单测里测不出来，
+ * 只能等到真机才暴露。
+ *
+ * 判据（与桌面 `tool-ui.tsx` 的按钮一一对应）：
+ * - `choice`（AI 提问）：`choose` 确认 / `deny` 取消 / `shelve` 暂存；`allow` 无意义；
+ * - `authorization`（授权）：`allow` / `deny` / `shelve`；`choose` 无意义；
+ * - `authorization + presentation: 'terminal'`（终端内确认）：**没有暂存语义**
+ *   （它是「命令已就绪，等你按回车」，没有可暂存的对象）。
+ *
+ * @returns 不合法时返回拒绝原因（固定 `unsupported-by-host`）；合法时返回 `null`。
+ */
+export function answerActionError(interaction, action) {
+    if (interaction.kind === 'choice') {
+        return action === 'allow' ? 'unsupported-by-host' : null;
+    }
+    if (action === 'choose')
+        return 'unsupported-by-host';
+    if (action === 'shelve' && interaction.presentation === 'terminal') {
+        return 'unsupported-by-host';
+    }
+    return null;
+}
+//# sourceMappingURL=answer.js.map

package/dist/protocol/answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.js","sourceRoot":"","sources":["../../src/protocol/answer.ts"],"names":[],"mappings":"AA0BA,uCAAuC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAEhC,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,QAAQ,GAAa,EAAE,CAAA;IAC3B,IAAI,WAAW,GAAG,EAAE,CAAA;IAEpB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,WAAW,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,QAAQ,GAAG,KAAK;aACb,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;aACjD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,OAAO,CAAC,CAAA;IACpB,CAAC;SAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,CAAC,GAAG,KAAsD,CAAA;QAChE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,QAAQ,GAAG,CAAC,CAAC,QAAQ;iBAClB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;iBACjD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpB,MAAM,CAAC,OAAO,CAAC,CAAA;QACpB,CAAC;QACD,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;YAAE,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAA;IAC3E,CAAC;SAAM,CAAC;QACN,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAA;IACjD,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,QAAQ,CAAC,MAAM;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACpD,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IACxC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,CAAA;AAClF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAA0D,EAC1D,MAAoB;IAEpB,IAAI,WAAW,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1D,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,qBAAqB,CAAA;IACrD,IAAI,MAAM,KAAK,QAAQ,IAAI,WAAW,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QACnE,OAAO,qBAAqB,CAAA;IAC9B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}