virlen-remote 0.4.0 → 0.6.1

package/src/protocol/host.ts

@@ -1,150 +1,205 @@
-/**
- * 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()
-    },
-  }
-}
+/**
+ * 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 {
+  AgentOptionDTO,
+  AnswerParams,
+  AnswerResult,
+  CompressParams,
+  ContextInfoDTO,
+  ContextParams,
+  CreateSessionParams,
+  DeleteMessageParams,
+  DeleteSessionParams,
+  FileListParams,
+  FileListResult,
+  FileReadParams,
+  FileReadResult,
+  FileWriteAbortParams,
+  FileWriteBeginParams,
+  FileWriteBeginResult,
+  FileWriteChunkParams,
+  FileWriteChunkResult,
+  FileWriteFinishParams,
+  FileWriteFinishResult,
+  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 }>
+  /**
+   * 删除单条消息及其之后的全部消息（截断）。
+   *
+   * ⚠️ 实现侧必须自己把三道闸都做上（不得依赖手机 UI）：
+   * 1. `confirm === true`（缺则 `E_CONFIRM_REQUIRED`）；
+   * 2. 会话**正在回复**时拒（`E_BUSY`）—— 删断正在跑的 run 会留下悬空工具调用；
+   * 3. 目标是 `role:'tool'` 的消息时拒（`E_BAD_REQUEST`）—— 工具结果与发起它的
+   *    assistant 消息是一体两面，单独删掉只会留下悬空调用。
+   *
+   * 结果不在应答里回传：实现侧负责推 `host.event.session.messages.reset`，
+   * 客户端重拉窗口（与压缩同一条一致性策略）。
+   */
+  deleteMessage(params: DeleteMessageParams): { 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 }>
+  /** 新建会话可选的 Agent 候选集（**只用于新建**，已有会话不可改）。 */
+  listAgents(): AgentOptionDTO[] | Promise<AgentOptionDTO[]>
+  /** 新建会话可选的工作目录候选集（**只用于新建**，已有会话不可改）。 */
+  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 }>
+  // ── §37：工作目录文件 ──
+  /**
+   * 列目录（实现侧必须自己过安全校验与 ACL）。
+   *
+   * ⚠️ 实现侧还要自己判「这条链路能不能传文件」（非中继）：那是**链路事实**，
+   * 不在本文档层能看到的范围里（见 `TransferTier` / `LinkKind`）。
+   */
+  listFiles(params: FileListParams): FileListResult | Promise<FileListResult>
+  /** 读一个分块（预览与下载同一条路）。 */
+  readFile(params: FileReadParams): FileReadResult | Promise<FileReadResult>
+  /** 上传：开始（校验 + 定名 + 建临时文件）。 */
+  beginFileWrite(params: FileWriteBeginParams): FileWriteBeginResult | Promise<FileWriteBeginResult>
+  /** 上传：写一块（偏移必须与已接收字节数一致）。 */
+  writeFileChunk(params: FileWriteChunkParams): FileWriteChunkResult | Promise<FileWriteChunkResult>
+  /** 上传：收尾（临时文件 → 目标名，原子落盘）。 */
+  finishFileWrite(params: FileWriteFinishParams): FileWriteFinishResult | Promise<FileWriteFinishResult>
+  /** 上传：放弃（删临时文件）。 */
+  abortFileWrite(params: FileWriteAbortParams): { 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.session.message.delete', async (params) => source.deleteMessage(params as DeleteMessageParams))
+  on('host.interaction.answer', async (params) => source.answer(params as AnswerParams))
+  on('host.interaction.list', async () => ({ interactions: await source.listInteractions() }))
+  // ── §22：模型 / Agent / 工作目录 / 上下文 ──
+  on('host.model.list', async () => ({ providers: await source.listModels() }))
+  on('host.session.setModel', async (params) => source.setModel(params as SetModelParams))
+  on('host.agent.list', async () => ({ agents: await source.listAgents() }))
+  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))
+  // ── §37：工作目录文件 ──
+  on('host.file.list', async (params) => source.listFiles(params as FileListParams))
+  on('host.file.read', async (params) => source.readFile(params as FileReadParams))
+  on('host.file.write.begin', async (params) => source.beginFileWrite(params as FileWriteBeginParams))
+  on('host.file.write.chunk', async (params) => source.writeFileChunk(params as FileWriteChunkParams))
+  on('host.file.write.finish', async (params) => source.finishFileWrite(params as FileWriteFinishParams))
+  on('host.file.write.abort', async (params) => source.abortFileWrite(params as FileWriteAbortParams))
+
+  return {
+    emit,
+    dispose() {
+      for (const dispose of disposers) dispose()
+    },
+  }
+}

package/src/protocol/message-actions.ts

@@ -0,0 +1,60 @@
+/**
+ * 消息级操作（引用 / 删除）—— **两端共用的契约**：能力名 + 引用引用体。
+ *
+ * ## 为什么这两个东西要放在共享包里
+ *
+ * 与 §33 的传输档位同一条理由：它们都是**两端各表一半**的约定。
+ *  - **引用**：手机端发 `SendParams.quotes`，电脑端把它组装成 `{type:'quote'}` 内容块；
+ *    手机端还要把 `MessageDTO.quotes` 渲染成引用条。字段名、角色取值域、快照语义
+ *    写两份必然漂移（一边 `quote`、一边 `quotes`，或一边 `assistant`、一边 `ai`）。
+ *  - **删除**：手机端长按菜单里的「删除」项**只在电脑端声明能力时才出现** ——
+ *    能力名是这里的常量，不是两边各写一遍的字面量（§33 的 `typeof` 绑定同一条教训）。
+ *
+ * ## 能力的两类语义（与 §33 的 `MESSAGE_DETAIL_CAPABILITY` 一致）
+ *
+ * 本包里导出的能力名有两种角色，**消费方必须分清**：
+ *  - **功能标记**（`MESSAGE_QUOTE_CAPABILITY` 与 §33 的 `MESSAGE_DETAIL_CAPABILITY`）：
+ *    只用来决定「界面给不给这个入口」，**不会被 ACL 的 `assert()` 拦**——引用本身就是
+ *    `session.send` 的一个参数，不是新的权限；
+ *  - **权限**（`MESSAGE_DELETE_CAPABILITY`）：删消息是**破坏性操作**，电脑端必须独立
+ *    `assert` 它，缺失即 `E_DENIED`——手机端不显示按钮**不是**防线（§7-⑪ 的教训）。
+ */
+
+/**
+ * 一条被引用消息的**快照引用**。
+ *
+ * ⚠️ `text` 是**快照**，不是外键：被引用的原消息可能随后被删除、被上下文压缩替换、
+ * 或滚出手机端的已加载窗口（§20.2 分页）—— 只存 `messageId` 的话，发给模型的引用内容
+ * 会在那些情形下凭空缺失，而用户界面上一无所知。这与桌面输入框的 `QuoteAttachment`
+ * **同一条口径**（`ui/pages/chat/components/input/hooks.ts`）。
+ *
+ * 角色取值域只有 `user` / `assistant`：**只有「有正文的两方发言」可被引用**。
+ * `tool`（工具输出）与 `system`（压缩摘要）不是对话发言，引用它们没有语义
+ * （桌面端的右键菜单同样不给它们「引用」项）。
+ */
+export interface MessageQuote {
+  /** 被引用消息的 id（同时用作 UI 列表 key / 去重键）。 */
+  messageId: string
+  /** 被引用消息的发送方。 */
+  role: 'user' | 'assistant'
+  /** 被引用消息的正文快照（原消息被删 / 被压缩后，引文仍然完整）。 */
+  text: string
+}
+
+/**
+ * 手机端声明它 = **长按气泡的菜单里提供「引用」**，并能把引用条渲染出来。
+ * 电脑端列出它 = **本机认识 `SendParams.quotes` 与 `MessageDTO.quotes`**。
+ *
+ * 为什么必须有这道闸（不是可选的礼貌）：**已部署的旧电脑端不认 `quotes` 参数** ——
+ * 它是普通字段，RPC 会正常成功，引文被静默丢掉。用户侧的表现是「我明明引用了，
+ * AI 却当没看见」，且没有任何报错可查。宁可对旧电脑端不显示这个入口。
+ */
+export const MESSAGE_QUOTE_CAPABILITY = 'message.quote'
+
+/**
+ * 删除单条消息（及其后全部）的能力名 —— 电脑端 ACL 必须声明它，手机端才显示「删除」项。
+ *
+ * 与上面那个不同，**这是权限而不是功能标记**：电脑端在 handler 里独立 `assert`，
+ * 未授权即 `E_DENIED`。手机端隐藏入口只是 UI 收敛，绝不构成防线（§7-⑪）。
+ */
+export const MESSAGE_DELETE_CAPABILITY = 'message.delete'

package/src/protocol/message-files.ts

@@ -0,0 +1,161 @@
+/**
+ * 消息里的**文件引用** —— **两端共用的契约**：能力名 + 引用体 + 校验口径。
+ *
+ * ## 这是什么（与桌面输入框的「文件附件」同一条口径）
+ *
+ * 手机端在文件面板里挑一个电脑上的文件，把它的**路径 + 展示元数据**挂到要发的那条消息上；
+ * 电脑端把它组装成 `{type:'file'}` 内容块交给引擎。**不搬运文件内容** ——
+ * 真正的读取交给 AI 用 `read_file` 工具按需完成（桌面端 `FileAttachment` 的文件头
+ * 写着同一条：「只存路径，不拷贝文件内容」）。
+ *
+ * ## 为什么必须放在共享包里
+ *
+ * 与 §36 的引用（`message-actions.ts`）同一条理由：它是**两端各表一半**的约定 ——
+ * 手机端发 `SendParams.files` 并把 `MessageDTO.files` 渲染成 chip，电脑端把前者组装成内容块、
+ * 把后者投影出来。字段名（`path` / `isDir` / `size`）与「路径分隔符统一成 `/`」的归一化
+ * 各写一份必然漂移，而漂移的症状是**静默的**：元数据对不上时 chip 显示成另一个东西，
+ * 没有任何报错可查。
+ *
+ * ## 校验为什么也在这里（而不是电脑侧自己写一份）
+ *
+ * `sanitizeFileRefs` 是**两端唯一的校验口径**：真电脑侧（`virlen-app/src/bridge/host-source.ts`）
+ * 与演示宿主（`testing/mock-host.ts`）都调它。若各写一份，mock 与真机会在「什么样的 `files`
+ * 算非法」上分叉 —— 而 mock 是单测的唯一参照物，分叉等于测试对着假行为发绿灯。
+ *
+ * ## 能力位的语义（与 §36 的 `MESSAGE_QUOTE_CAPABILITY` 一致）
+ *
+ * `MESSAGE_FILE_CAPABILITY` 是**功能标记**，不是权限：文件引用本身就是 `session.send` 的一个
+ * 参数（越权防线仍是 ACL 里的 `session.send`）。写进本表只为让手机端知道
+ * 「本机电脑端认识 `files`」—— 旧电脑端会把未知字段**静默丢掉**，用户侧的表现是
+ * 「我明明附了文件，AI 却当没看见」，且没有任何报错可查。宁可对旧电脑端不显示这个入口。
+ */
+import { FILE_NAME_MAX_LEN } from './files'
+
+/**
+ * 手机端声明它 = **文件面板能给「引用」入口**，并能渲染 `MessageDTO.files` 的 chip。
+ * 电脑端列出它 = **本机认识 `SendParams.files` 与 `MessageDTO.files`**。
+ */
+export const MESSAGE_FILE_CAPABILITY = 'message.file'
+
+/**
+ * 一条消息最多能带几个文件引用。
+ *
+ * 上限的意义有两层：① 超过之后模型也只是「看得到一堆路径」，边际收益为零；
+ * ② 它是**载荷上界**（每个引用都在消息里，且会随消息一起持久化 / 导出 / 重放）。
+ * 超限**拒整条**而不是截断：截断是静默的 —— 手机端的 chip 还在，用户会以为都带上了。
+ */
+export const MESSAGE_FILE_MAX = 20
+
+/**
+ * 单个引用路径的长度上限（1024 字符）。
+ *
+ * 与 `MESSAGE_FILE_MAX` 同一条纪律：路径是**手机端给的字符串**，没有上界就等于允许
+ * 一个（有 bug 或被改写的）客户端把任意长的内容塞进消息里。正常路径远低于这个数
+ * （Windows 的 `MAX_PATH` 是 260）。
+ */
+export const MESSAGE_FILE_PATH_MAX = 1024
+
+/**
+ * 一条**文件引用**（手机端 → 电脑端 → 引擎内容块）。
+ *
+ * ⚠️ 与 `MessageQuote` 不同，这里**不是快照**：存的是路径，AI 读的那一刻磁盘上是什么就是什么。
+ * 这正是「不搬运内容」的代价，也是它的好处（引用的永远是**当前**内容，不会拿一份过期副本
+ * 去回答）。桌面端的文件附件同此语义。
+ */
+export interface MessageFileRef {
+  /** 文件绝对路径（分隔符按契约统一为 `/`，见 `sanitizeFileRefs`）。 */
+  path: string
+  /** 文件名（含扩展名）—— chip 上显示的就是它。 */
+  name: string
+  /** 是否为目录（目录也能被引用：模型用 `list_files` 去看里面有什么）。 */
+  isDir?: boolean
+  /** 字节数（目录没有这一项）。只用于展示，**不作为任何校验依据**（它不是文件的事实来源）。 */
+  size?: number
+}
+
+/**
+ * 校验结果。
+ *
+ * ⚠️ **刻意不写成判别联合**（`| { ok: true; files } | { ok: false; reason }`）：
+ * 布尔字面量的判别联合靠 `strictNullChecks` 才能收窄，而消费方 `virlen-app` 的 tsconfig 是
+ * `strictNullChecks: false` —— 写成判别联合的话，电脑侧那句 `if (!r.ok) { …r.reason… }`
+ * 根本收窄不了（直接 `TS2339: Property 'reason' does not exist`）。契约放在共享包里，
+ * 就不能只在一边成立。
+ *
+ * 不变式：`ok === (reason === '')`（通过时 `reason` 是空串，`files` 是被归一化的引用；
+ * 被拒时 `files` 恒为空数组）。
+ */
+export interface FileRefSanitizeResult {
+  /** 是否通过校验。 */
+  ok: boolean
+  /** 归一化后的引用；被拒时恒为空数组（调用方那时应该直接抛错）。 */
+  files: MessageFileRef[]
+  /** 被拒原因（可直接显示给用户）；通过时为空串。 */
+  reason: string
+}
+
+/**
+ * 校验并归一化手机传来的文件引用（**电脑侧与演示宿主共用这一份**）。
+ *
+ * 规则：
+ *  - 缺省 / `null` → 空数组（不带文件引用是完全正常的一条消息）；
+ *  - 不是数组 / 条目不是对象 / `path` 不是非空字符串 → **整条拒**（返回 `ok:false`）；
+ *  - 路径超过 `MESSAGE_FILE_PATH_MAX`、条目数超过 `MESSAGE_FILE_MAX` → 整条拒；
+ *  - `name` 缺失或为空 → 用路径末段兜底（电脑侧从内容块投影回来时也会用到这条）；
+ *  - `isDir` / `size` 形状不对 → **丢掉该字段**（它们是展示元数据，说谎也只是 chip 上少一行字），
+ *    但路径非法必须拒 —— 那是这条引用**唯一有语义的部分**。
+ *  - 路径分隔符 `\` → `/`（与全项目的路径口径一致，两侧拼串才不会出现 `a\/b`）；
+ *  - 同一路径只保留第一次出现的（手机端连点两下不该变成两条引用）。
+ *
+ * ## 为什么非法就整条拒（而不是「丢掉那一条、其余照发」）
+ *
+ * §36 的教训：**假绿灯比报错难查得多**。丢掉一条引用时，手机端那边的 chip 还在输入框里、
+ * 发完消息里也有它 —— 用户会以为带上了，而 AI 从未看到。拒掉整条之后，用户看到的是
+ * 一条明确的失败提示，芯片还在，可以改完再发。
+ */
+export function sanitizeFileRefs(input: unknown): FileRefSanitizeResult {
+  /** 被拒（`files` 恒为空数组 —— 失败就是**整条**失败，没有「部分成功」这个态） */
+  const reject = (reason: string): FileRefSanitizeResult => ({ ok: false, files: [], reason })
+
+  if (input == null) return { ok: true, files: [], reason: '' }
+  if (!Array.isArray(input)) return reject('文件引用的形状不对')
+  if (input.length > MESSAGE_FILE_MAX) {
+    return reject(`一次最多引用 ${MESSAGE_FILE_MAX} 个文件`)
+  }
+
+  const files: MessageFileRef[] = []
+  const seen = new Set<string>()
+  for (const raw of input) {
+    if (typeof raw !== 'object' || raw === null) {
+      return reject('文件引用的形状不对')
+    }
+    const item = raw as Partial<MessageFileRef>
+    if (typeof item.path !== 'string' || !item.path.trim()) {
+      return reject('文件引用缺少路径')
+    }
+    // 归一化分隔符：`E:\a\b` → `E:/a/b`（与 `normalizeWorkspace` / 文件面板同一口径）
+    const path = item.path.replace(/\\/g, '/')
+    if (path.length > MESSAGE_FILE_PATH_MAX) {
+      return reject('文件路径过长')
+    }
+    if (seen.has(path)) continue
+    seen.add(path)
+
+    const name = typeof item.name === 'string' ? item.name.trim() : ''
+    files.push({
+      path,
+      name: (name || baseName(path)).slice(0, FILE_NAME_MAX_LEN),
+      ...(typeof item.isDir === 'boolean' ? { isDir: item.isDir } : {}),
+      ...(typeof item.size === 'number' && Number.isFinite(item.size) && item.size >= 0
+        ? { size: item.size }
+        : {}),
+    })
+  }
+  return { ok: true, files, reason: '' }
+}
+
+/** 路径末段（`name` 缺失时的兜底；本地实现以免把 `protocol/files` 的整套路径工具拖进来）。 */
+function baseName(path: string): string {
+  const parts = path.replace(/\/+$/, '').split('/')
+  return parts[parts.length - 1] || path
+}