dsh-plugin-mobile-link 0.7.0 → 0.8.1

package/lib/history/question-record.js

@@ -0,0 +1,186 @@
+/**
+ * 作答记录（`+link/question`）：把 `ask_user_question` 的问题与答案单独下发。
+ *
+ * 为什么需要：折叠模式把 `tool/call` / `tool/result` 整段收进摘要，正文与参数都不
+ * 下发；但用户刚做出的选择属于**用户自己的输入**，不能因为它来自工具结果就跟着
+ * 过程一起消失（SR-02.16）。桌面把这种记录渲染成一条用户消息气泡，手机侧沿用同一
+ * 语义：它是会话内容，不是过程。
+ *
+ * 形状：
+ *
+ *     +link/question {
+ *       callId,
+ *       questions: [{ id, question, header? }],
+ *       answers:   [{ id, selected: string[], custom?: string }]
+ *     }
+ *
+ * - 只发**已结算**的答案批次；`{pending:true}` 的计时提问、失败或取消的调用不发。
+ * - 问题文字从 `tool/call` 参数里取；参数缺失/形状不认识时给空数组，客户端至少
+ *   还能显示答案（AR-02.16.01 的降级口径）。
+ * - 文字按码元截断且不切开代理对（与预览、搜索片段同一套 `truncateSafe`）。
+ */
+
+import { truncateSafe } from '../unicode.js'
+
+/** 记录类型。以 `+` 开头，不会与宿主事件类型相撞。 */
+export const QUESTION_RECORD_TYPE = '+link/question'
+
+/** 会带来问题清单的工具名。 */
+const QUESTION_TOOLS = new Set(['ask_user_question', 'request_user_input'])
+
+/** 单个字段（问题、标题、自定义答案）下发的上限；超出截断并加省略号。 */
+export const QUESTION_TEXT_LIMIT = 1000
+
+export function isQuestionTool(name) {
+  return typeof name === 'string' && QUESTION_TOOLS.has(name)
+}
+
+/**
+ * 工具结果的正文。与摘要的字节统计、搜索的 `docText` 同一组键。
+ * 只取文本块与文本字段，图片/文件不在其中。
+ */
+export function resultTextOf(data) {
+  const parts = []
+  const blocks = [data?.message?.content, data?.content].find((value) => Array.isArray(value)) ?? []
+  for (const block of blocks) {
+    if (typeof block?.text === 'string' && block.text.length > 0) parts.push(block.text)
+  }
+  for (const key of ['output', 'result', 'stdout', 'stderr', 'text']) {
+    if (typeof data?.[key] === 'string' && data[key].length > 0) parts.push(data[key])
+  }
+  return parts.join('\n')
+}
+
+function parseJson(value) {
+  if (typeof value !== 'string') return undefined
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/** 截到上限并补省略号；截断点不落在 emoji 中间。 */
+function cap(text) {
+  if (typeof text !== 'string') return ''
+  if (text.length <= QUESTION_TEXT_LIMIT) return text
+  return `${truncateSafe(text, QUESTION_TEXT_LIMIT - 1)}…`
+}
+
+/**
+ * `tool/call` 参数里的问题清单。
+ *
+ * 严格配对：任何一项缺 `id` / `question` 就整份不要——半份问题清单会把答案配到
+ * 错的问题上，比没有文字更糟。`multi_select` / `multiSelect` 两种拼写都收
+ * （宿主 schema 用蛇形，旧夹具可能用驼峰），展示只需要文字。
+ */
+export function questionsOf(argumentsValue) {
+  const parsed = typeof argumentsValue === 'object' && argumentsValue !== null
+    ? argumentsValue
+    : parseJson(argumentsValue)
+  if (parsed === null || typeof parsed !== 'object') return []
+  if (!Array.isArray(parsed.questions) || parsed.questions.length === 0) return []
+  const out = []
+  for (const question of parsed.questions) {
+    if (question === null || typeof question !== 'object') return []
+    if (typeof question.id !== 'string' || question.id === '') return []
+    if (typeof question.question !== 'string') return []
+    out.push({
+      id: question.id,
+      question: cap(question.question),
+      ...(typeof question.header === 'string' && question.header !== ''
+        ? { header: cap(question.header) }
+        : {}),
+    })
+  }
+  return out
+}
+
+/**
+ * 工具结果里的答案批次；没结算、形状不认识时返回 null。
+ *
+ * `answers: []` 保留为空数组（调用方据此不发记录）：它表示"没有可显示的答案"，
+ * 与"结果还没回来"不是同一件事。
+ */
+export function answersOf(resultText) {
+  const parsed = parseJson(resultText)
+  if (parsed === null || typeof parsed !== 'object') return null
+  if (parsed.pending === true) return null
+  if (!Array.isArray(parsed.answers)) return null
+  const out = []
+  for (const answer of parsed.answers) {
+    if (answer === null || typeof answer !== 'object') return null
+    if (typeof answer.id !== 'string' || answer.id === '') return null
+    if (!Array.isArray(answer.selected) || !answer.selected.every((item) => typeof item === 'string')) {
+      return null
+    }
+    if (answer.custom !== undefined && typeof answer.custom !== 'string') return null
+    out.push({
+      id: answer.id,
+      selected: answer.selected,
+      ...(typeof answer.custom === 'string' && answer.custom.trim() !== ''
+        ? { custom: cap(answer.custom) }
+        : {}),
+    })
+  }
+  return out
+}
+
+/**
+ * 一次提问调用 + 它的结果 → 一条待下发的记录。
+ *
+ * @param {object} input
+ * @param {{callId?: string, name?: string, arguments?: unknown}} input.call
+ * @param {string} input.resultText 工具结果正文
+ * @param {number} input.seq 结果事件的 seq（记录的排序键）
+ * @param {number} [input.time] 结果事件时间
+ * @returns {object|null} 不是提问、没结算、或 callId 缺失时返回 null
+ */
+export function questionRecordFor({ call, resultText, seq, time }) {
+  if (!isQuestionTool(call?.name)) return null
+  if (typeof call?.callId !== 'string' || call.callId === '') return null
+  if (!Number.isInteger(seq)) return null
+  const answers = answersOf(resultText)
+  if (answers === null || answers.length === 0) return null
+  return {
+    type: QUESTION_RECORD_TYPE,
+    seq,
+    ...(Number.isFinite(time) ? { time } : {}),
+    data: {
+      callId: call.callId,
+      questions: questionsOf(call.arguments),
+      answers,
+    },
+  }
+}
+
+/**
+ * 从原始记录里取出提问结果，供 v1/v2 两条折叠路径共用。
+ * @param {Array<{type:string,event:object}>} records
+ * @returns {Array<{seq:number,record:object}>} 按 seq 升序
+ */
+export function questionRecordsOfEvents(events) {
+  const calls = new Map()
+  const out = []
+  for (const event of events) {
+    if (event?.type === 'tool/call' && isQuestionTool(event?.data?.name)) {
+      const callId = event?.data?.callId
+      if (typeof callId === 'string' && callId !== '') {
+        calls.set(callId, { callId, name: event.data.name, arguments: event.data.arguments })
+      }
+      continue
+    }
+    if (event?.type !== 'tool/result') continue
+    const callId = event?.data?.message?.toolCallId ?? event?.data?.toolCallId ?? event?.data?.callId
+    const call = calls.get(callId)
+    if (call === undefined) continue
+    const record = questionRecordFor({
+      call,
+      resultText: resultTextOf(event.data),
+      seq: event.seq,
+      time: event.time,
+    })
+    if (record !== null) out.push({ seq: event.seq, record })
+  }
+  return out
+}

package/lib/i18n.js

@@ -0,0 +1,177 @@
+// CLI and status hints are user-facing too. Keep their catalogs separate from the
+// panel bundle (which is hand-inlined) so the headless path can be localized
+// without pulling the browser client into the CLI.
+const CATALOGS = {
+  en: {
+    'cli.registered': 'This computer is registered. Two steps remain:',
+    'cli.step1': 'Restart DSH so the connector uses this identity;',
+    'cli.step2': 'Scan the QR code below with the phone app (same as the Mobile link panel).',
+    'cli.code': 'Pairing code ${code} (valid about ${minutes} minutes, one-time)',
+    'cli.hint': 'You can also open the Mobile link panel for a new code; the connector writes the tokenized endpoint to ~/.dsh/mobile-link/endpoint.json.',
+    'cli.prefetchFailed': 'Could not prefetch a pairing code: ${error}',
+    'cli.prefetchHint': 'After restarting DSH, open the Mobile link panel and scan its QR code with the phone app.',
+    'status.config': 'The local address you configured is wrong or stale.',
+    'status.hostService': 'This host did not expose its local address to the connector; the plugin is probably not loaded into the running host.',
+    'status.dshWebUrl': 'The local address in the environment variable is stale.',
+    'status.unreachable': 'The local DSH is unreachable; check that the host is running.',
+    'status.desktop': 'You are using the official desktop app (the connector is installed in its profile).',
+    'status.web': 'You are using the command-line web host.',
+    'status.unknown': 'The host could not be identified; if it cannot connect, follow the troubleshooting section.',
+    'status.unregistered': 'This computer is not registered with the relay yet. Check the relay address in the Mobile link panel, then click Register.',
+  },
+  'zh-Hans': {
+    'cli.registered': '这台电脑已登记。接下来还有两步：',
+    'cli.step1': '重启 DSH，让连接器用上这个身份；',
+    'cli.step2': '手机 App 的「扫码配对」扫下面的二维码（与 DSH 界面左下角「移动端连接」里那张等价）。',
+    'cli.code': '配对码 ${code}（约 ${minutes} 分钟有效，一次性）',
+    'cli.hint': '也可以在这台电脑上点 DSH 界面左下角的「移动端连接」取新码；连接器还会把带令牌地址写进 ~/.dsh/mobile-link/endpoint.json。',
+    'cli.prefetchFailed': '（这次没能预先申请配对码：${error}）',
+    'cli.prefetchHint': '重启 DSH 后，在这台电脑的 DSH 界面左下角点「移动端连接」，用手机 App 的「扫码配对」扫里面的二维码。',
+    'status.config': '你手工配置的本机地址不对或已失效',
+    'status.hostService': '当前宿主没有把本机访问方式交给插件（多为插件没装进正在运行的宿主）',
+    'status.dshWebUrl': '环境变量里的本机地址已过期',
+    'status.unreachable': '本机 DSH 不可达；请确认宿主正在运行',
+    'status.desktop': '你正在用官方桌面版（连接器已装进它的档案）',
+    'status.web': '你正在用命令行 web 版',
+    'status.unknown': '无法识别当前宿主；若连不上，请按"排查"一节处理',
+    'status.unregistered': '这台电脑还没有登记到中转。在「移动端连接」面板里确认中转地址，然后点「登记」。',
+  },
+  'zh-Hant': {
+    'cli.registered': '這台電腦已登記。接下來還有兩步：',
+    'cli.step1': '重新啟動 DSH，讓連接器使用這個身分；',
+    'cli.step2': '用手機 App 的「掃描 QR code」掃描下方 QR code（與 DSH 介面左下角「手機連結」裡的那張相同）。',
+    'cli.code': '配對碼 ${code}（約 ${minutes} 分鐘內有效，一次性）',
+    'cli.hint': '也可以在這台電腦上點 DSH 介面左下角的「手機連結」取得新碼；連接器也會把帶權杖的位址寫入 ~/.dsh/mobile-link/endpoint.json。',
+    'cli.prefetchFailed': '（這次無法預先取得配對碼：${error}）',
+    'cli.prefetchHint': '重新啟動 DSH 後，在這台電腦的 DSH 介面左下角點「手機連結」，用手機 App 的「掃描 QR code」掃描裡面的 QR code。',
+    'status.config': '你手動設定的本機位址不正確或已失效',
+    'status.hostService': '目前宿主沒有把本機存取方式交給外掛（多為外掛沒有載入執行中的宿主）',
+    'status.dshWebUrl': '環境變數中的本機位址已過期',
+    'status.unreachable': '本機 DSH 無法連線；請確認宿主正在執行',
+    'status.desktop': '你正在使用官方桌面版（連接器已安裝在它的設定檔中）',
+    'status.web': '你正在使用命令列 web 版',
+    'status.unknown': '無法辨識目前宿主；若無法連線，請依「疑難排解」一節處理',
+    'status.unregistered': '這台電腦尚未登記到中繼。在「手機連結」面板確認中繼位址，然後點「登記」。',
+  },
+  ja: {
+    'cli.registered': 'このコンピューターは登録されました。残り 2 ステップです：',
+    'cli.step1': 'DSH を再起動して、コネクタがこの ID を使うようにします。',
+    'cli.step2': 'スマートフォンアプリで下の QR コードをスキャンします（「モバイルリンク」パネルのものと同じです）。',
+    'cli.code': 'ペアリングコード ${code}（約 ${minutes} 分間有効、1 回限り）',
+    'cli.hint': 'DSH 左下の「モバイルリンク」から新しいコードを取得することもできます。コネクタはトークン付きのエンドポイントを ~/.dsh/mobile-link/endpoint.json に書き込みます。',
+    'cli.prefetchFailed': '（ペアリングコードを事前に取得できませんでした：${error}）',
+    'cli.prefetchHint': 'DSH を再起動した後、DSH 左下の「モバイルリンク」を開き、スマートフォンアプリで QR コードをスキャンしてください。',
+    'status.config': '手動で設定したローカルアドレスが正しくないか、期限切れです。',
+    'status.hostService': 'このホストはローカルアドレスをコネクタに渡していません。プラグインが実行中のホストに読み込まれていない可能性があります。',
+    'status.dshWebUrl': '環境変数のローカルアドレスが期限切れです。',
+    'status.unreachable': 'ローカルの DSH に到達できません。ホストが実行中か確認してください。',
+    'status.desktop': '公式デスクトップアプリを使用しています（コネクタはそのプロファイルにインストールされています）。',
+    'status.web': 'コマンドライン web ホストを使用しています。',
+    'status.unknown': 'ホストを特定できません。接続できない場合はトラブルシューティングの節を参照してください。',
+    'status.unregistered': 'このコンピューターはまだリレーに登録されていません。「モバイルリンク」パネルでリレーアドレスを確認し、「登録」をクリックしてください。',
+  },
+  ko: {
+    'cli.registered': '이 컴퓨터가 등록되었습니다. 두 단계가 남았습니다:',
+    'cli.step1': 'DSH를 다시 시작하여 커넥터가 이 ID를 사용하도록 합니다.',
+    'cli.step2': '휴대폰 앱으로 아래 QR 코드를 스캔합니다(모바일 링크 패널과 동일).',
+    'cli.code': '페어링 코드 ${code}(약 ${minutes}분 유효, 일회용)',
+    'cli.hint': 'DSH 왼쪽 아래의 모바일 링크 패널에서 새 코드를 받을 수도 있습니다. 커넥터는 토큰이 포함된 주소를 ~/.dsh/mobile-link/endpoint.json에 기록합니다.',
+    'cli.prefetchFailed': '(페어링 코드를 미리 가져오지 못했습니다: ${error})',
+    'cli.prefetchHint': 'DSH를 다시 시작한 뒤 DSH 왼쪽 아래의 모바일 링크 패널을 열고 휴대폰 앱으로 QR 코드를 스캔하세요.',
+    'status.config': '직접 설정한 로컬 주소가 잘못되었거나 만료되었습니다.',
+    'status.hostService': '이 호스트가 로컬 주소를 커넥터에 전달하지 않았습니다. 플러그인이 실행 중인 호스트에 로드되지 않았을 수 있습니다.',
+    'status.dshWebUrl': '환경 변수의 로컬 주소가 만료되었습니다.',
+    'status.unreachable': '로컬 DSH에 연결할 수 없습니다. 호스트가 실행 중인지 확인하세요.',
+    'status.desktop': '공식 데스크톱 앱을 사용 중입니다(커넥터가 해당 프로필에 설치되어 있습니다).',
+    'status.web': '명령줄 web 호스트를 사용 중입니다.',
+    'status.unknown': '호스트를 식별할 수 없습니다. 연결할 수 없으면 문제 해결 절을 따르세요.',
+    'status.unregistered': '이 컴퓨터는 아직 릴레이에 등록되지 않았습니다. 모바일 링크 패널에서 릴레이 주소를 확인한 뒤 등록을 클릭하세요.',
+  },
+  es: {
+    'cli.registered': 'Este equipo está registrado. Quedan dos pasos:',
+    'cli.step1': 'Reinicia DSH para que el conector use esta identidad;',
+    'cli.step2': 'Escanea el código QR de abajo con la app del teléfono (el mismo del panel Mobile link).',
+    'cli.code': 'Código de emparejamiento ${code} (válido unos ${minutes} minutos, de un solo uso)',
+    'cli.hint': 'También puedes abrir el panel Mobile link para obtener un código nuevo; el conector escribe el endpoint con token en ~/.dsh/mobile-link/endpoint.json.',
+    'cli.prefetchFailed': 'No se pudo obtener un código de emparejamiento por adelantado: ${error}',
+    'cli.prefetchHint': 'Después de reiniciar DSH, abre el panel Mobile link y escanea su código QR con la app del teléfono.',
+    'status.config': 'La dirección local que configuraste es incorrecta o ha caducado.',
+    'status.hostService': 'Este host no expuso su dirección local al conector; probablemente el plugin no está cargado en el host en ejecución.',
+    'status.dshWebUrl': 'La dirección local de la variable de entorno ha caducado.',
+    'status.unreachable': 'No se puede acceder al DSH local; comprueba que el host esté en ejecución.',
+    'status.desktop': 'Estás usando la app de escritorio oficial (el conector está instalado en su perfil).',
+    'status.web': 'Estás usando el host web de línea de comandos.',
+    'status.unknown': 'No se pudo identificar el host; si no conecta, sigue la sección de solución de problemas.',
+    'status.unregistered': 'Este equipo aún no está registrado en el relay. Comprueba la dirección del relay en el panel Mobile link y pulsa Registrar.',
+  },
+  'pt-BR': {
+    'cli.registered': 'Este computador está registrado. Faltam dois passos:',
+    'cli.step1': 'Reinicie o DSH para que o conector use esta identidade;',
+    'cli.step2': 'Escaneie o QR code abaixo com o app do celular (o mesmo do painel Mobile link).',
+    'cli.code': 'Código de pareamento ${code} (válido por cerca de ${minutes} minutos, uso único)',
+    'cli.hint': 'Você também pode abrir o painel Mobile link para obter um novo código; o conector grava o endpoint com token em ~/.dsh/mobile-link/endpoint.json.',
+    'cli.prefetchFailed': 'Não foi possível obter um código de pareamento antecipadamente: ${error}',
+    'cli.prefetchHint': 'Depois de reiniciar o DSH, abra o painel Mobile link e escaneie o QR code com o app do celular.',
+    'status.config': 'O endereço local configurado está incorreto ou expirou.',
+    'status.hostService': 'Este host não expôs o endereço local ao conector; provavelmente o plugin não está carregado no host em execução.',
+    'status.dshWebUrl': 'O endereço local da variável de ambiente expirou.',
+    'status.unreachable': 'O DSH local não está acessível; verifique se o host está em execução.',
+    'status.desktop': 'Você está usando o app de desktop oficial (o conector está instalado no perfil dele).',
+    'status.web': 'Você está usando o host web de linha de comando.',
+    'status.unknown': 'Não foi possível identificar o host; se não conectar, siga a seção de solução de problemas.',
+    'status.unregistered': 'Este computador ainda não está registrado no relay. Verifique o endereço do relay no painel Mobile link e clique em Registrar.',
+  },
+  fr: {
+    'cli.registered': 'Cet ordinateur est enregistré. Il reste deux étapes :',
+    'cli.step1': "Redémarrez DSH pour que le connecteur utilise cette identité ;",
+    'cli.step2': "Scannez le QR code ci-dessous avec l'application mobile (le même que dans le panneau Mobile link).",
+    'cli.code': 'Code d’appairage ${code} (valable environ ${minutes} minutes, à usage unique)',
+    'cli.hint': "Vous pouvez aussi ouvrir le panneau Mobile link pour obtenir un nouveau code ; le connecteur écrit l'endpoint avec jeton dans ~/.dsh/mobile-link/endpoint.json.",
+    'cli.prefetchFailed': "Impossible de précharger un code d'appairage : ${error}",
+    'cli.prefetchHint': "Après avoir redémarré DSH, ouvrez le panneau Mobile link et scannez son QR code avec l'application mobile.",
+    'status.config': "L'adresse locale configurée est incorrecte ou obsolète.",
+    'status.hostService': "Cet hôte n'a pas exposé son adresse locale au connecteur ; le plugin n'est probablement pas chargé dans l'hôte en cours.",
+    'status.dshWebUrl': "L'adresse locale de la variable d'environnement est obsolète.",
+    'status.unreachable': 'Le DSH local est inaccessible ; vérifiez que l’hôte est en cours d’exécution.',
+    'status.desktop': "Vous utilisez l'application de bureau officielle (le connecteur est installé dans son profil).",
+    'status.web': 'Vous utilisez l’hôte web en ligne de commande.',
+    'status.unknown': "L'hôte n'a pas pu être identifié ; si la connexion échoue, suivez la section de dépannage.",
+    'status.unregistered': "Cet ordinateur n'est pas encore enregistré auprès du relais. Vérifiez l'adresse du relais dans le panneau Mobile link, puis cliquez sur Enregistrer.",
+  },
+  de: {
+    'cli.registered': 'Dieser Computer ist registriert. Es fehlen noch zwei Schritte:',
+    'cli.step1': 'DSH neu starten, damit der Connector diese Identität verwendet;',
+    'cli.step2': 'Den QR-Code unten mit der Telefon-App scannen (derselbe wie im Mobile-link-Panel).',
+    'cli.code': 'Kopplungscode ${code} (etwa ${minutes} Minuten gültig, einmalig)',
+    'cli.hint': 'Du kannst auch im Mobile-link-Panel einen neuen Code holen; der Connector schreibt den Endpunkt mit Token nach ~/.dsh/mobile-link/endpoint.json.',
+    'cli.prefetchFailed': 'Kopplungscode konnte nicht vorab geholt werden: ${error}',
+    'cli.prefetchHint': 'Nach dem Neustart von DSH das Mobile-link-Panel öffnen und den QR-Code mit der Telefon-App scannen.',
+    'status.config': 'Die manuell konfigurierte lokale Adresse ist falsch oder veraltet.',
+    'status.hostService': 'Dieser Host hat dem Connector seine lokale Adresse nicht übergeben; das Plugin ist vermutlich nicht im laufenden Host geladen.',
+    'status.dshWebUrl': 'Die lokale Adresse in der Umgebungsvariable ist veraltet.',
+    'status.unreachable': 'Das lokale DSH ist nicht erreichbar; prüfe, ob der Host läuft.',
+    'status.desktop': 'Du verwendest die offizielle Desktop-App (der Connector ist in ihrem Profil installiert).',
+    'status.web': 'Du verwendest den Web-Host der Kommandozeile.',
+    'status.unknown': 'Der Host konnte nicht erkannt werden; wenn keine Verbindung möglich ist, folge dem Abschnitt zur Fehlerbehebung.',
+    'status.unregistered': 'Dieser Computer ist noch nicht beim Relay registriert. Prüfe die Relay-Adresse im Mobile-link-Panel und klicke auf Registrieren.',
+  },
+}
+const ALIASES = { zh: 'zh-Hans', 'zh-Hans': 'zh-Hans', 'zh-CN': 'zh-Hans', 'zh-Hant': 'zh-Hant', 'zh-TW': 'zh-Hant', 'zh-HK': 'zh-Hant', ja: 'ja', ko: 'ko', es: 'es', pt: 'pt-BR', 'pt-BR': 'pt-BR', fr: 'fr', de: 'de', en: 'en' }
+let language = 'zh-Hans'
+export function resolveLanguage(tag) {
+  if (!tag) return null
+  const value = String(tag).trim().replace('_', '-')
+  if (ALIASES[value]) return ALIASES[value]
+  const base = value.toLowerCase().split('-')[0]
+  return ALIASES[base] ?? null
+}
+export function setLanguage(tag) {
+  const next = resolveLanguage(tag)
+  if (next) language = next
+  return language
+}
+export function currentLanguage() { return language }
+export function T(key, vars = {}) {
+  const text = CATALOGS[language]?.[key] ?? CATALOGS['zh-Hans'][key] ?? key
+  return text.replace(/\$\{(\w+)\}/g, (m, name) => (name in vars ? String(vars[name]) : m))
+}

package/lib/image-originals.js

@@ -0,0 +1,121 @@
+/**
+ * 预览 ↔ 原图 的关联索引（Host 侧持久状态）。
+ *
+ * 为什么需要它：Host 的 `session/attachment` 只认**图像**引用，没有按文件引用
+ * 读回字节的 RPC；而一张图的原图是逐字节保存的 file 附件（`FileAttachmentRef`），
+ * 与 Host 归一化后的预览图是两个内容地址。手机要"按需取原图"，就必须能从预览的
+ * `attachmentId` 找到原图引用。
+ *
+ * 关联放在**电脑上**而不是 App 里：需求要求重装、重新配对、换设备后仍能取回原图，
+ * 而客户端的任何缓存都会在重装时消失。键是预览的 `attachmentId`（内容哈希，全局唯一），
+ * 所以索引不需要会话信息。写这条索引的有两处：连接器（手机发送的图）与
+ * `send_image` 插件（工具结果图），格式见 `docs/IMAGE-VARIANTS.md` 与 /tmp 契约 §1.4。
+ *
+ * 追加写而不是重写：两个写者（连接器与图片插件）在同一进程里，但各自是独立的模块实例，
+ * 读-改-写会互相覆盖。`O_APPEND` 的单次整行写入在 POSIX 上不会交错；读取端按行解析、
+ * 同一预览取最后一条。索引坏掉最坏的后果是"原图不可用"，绝不会变成错误或数据丢失。
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, writeSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { dshHome } from './state.js'
+
+/** 索引版本；字段变化时递增，读取端忽略不认识的版本。 */
+export const INDEX_VERSION = 1
+
+/** 索引文件最大可读字节数：超过说明文件被写坏了，宁可不认也不要整读进内存。 */
+export const MAX_INDEX_BYTES = 8 * 1024 * 1024
+
+/** 索引文件路径（`$DSH_HOME/mobile-link/image-originals.jsonl`）。 */
+export function indexPath(home = dshHome()) {
+  return join(home, 'mobile-link', 'image-originals.jsonl')
+}
+
+/** 一条索引记录。字段与图片插件的写入端必须一致。 */
+export function indexEntry({ previewId, original, source = 'composer', savedAt = new Date().toISOString() }) {
+  return {
+    v: INDEX_VERSION,
+    previewId,
+    original: {
+      attachmentId: original.attachmentId,
+      name: original.name,
+      bytes: original.bytes,
+      ...(original.mediaType === undefined ? {} : { mediaType: original.mediaType }),
+    },
+    savedAt,
+    source,
+  }
+}
+
+/**
+ * 追加一条记录。
+ *
+ * 失败只上报给日志，不抛给调用方：原图已经存进 Host 的对象库了，索引写不进去
+ * 只意味着"这张图暂时取不到原图"，不该让整次发送失败。
+ * @returns {boolean} 是否写入成功（测试与诊断使用）。
+ */
+export function appendIndex(entry, { home = dshHome(), logger = console } = {}) {
+  const path = indexPath(home)
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    const line = `${JSON.stringify(entry)}\n`
+    const fd = openSync(path, 'a', 0o600)
+    try {
+      writeSync(fd, line)
+    } finally {
+      closeSync(fd)
+    }
+    return true
+  } catch (error) {
+    logger.warn?.(`mobile-link: image-originals append failed: ${error?.message ?? error}`)
+    return false
+  }
+}
+
+/**
+ * 把整个索引读成 `previewId → 原图元数据`。
+ *
+ * 坏行（半行、JSON 不完整、字段类型不对）逐行跳过；同键后写覆盖先写。
+ * 文件不存在返回空表——"没有原图"是正常状态，不是错误。
+ */
+export function readIndex({ home = dshHome() } = {}) {
+  const path = indexPath(home)
+  let text
+  try {
+    if (statSync(path).size > MAX_INDEX_BYTES) return new Map()
+    text = readFileSync(path, 'utf8')
+  } catch {
+    return new Map()
+  }
+  const map = new Map()
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    let parsed
+    try {
+      parsed = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (parsed?.v !== INDEX_VERSION) continue
+    const previewId = parsed.previewId
+    const original = parsed.original
+    if (typeof previewId !== 'string' || previewId.length === 0) continue
+    if (typeof original?.attachmentId !== 'string' || !original.attachmentId) continue
+    if (typeof original.name !== 'string' || !original.name) continue
+    if (!Number.isSafeInteger(original.bytes) || original.bytes < 0) continue
+    map.set(previewId, {
+      attachmentId: original.attachmentId,
+      name: original.name,
+      bytes: original.bytes,
+      ...(typeof original.mediaType === 'string' ? { mediaType: original.mediaType } : {}),
+    })
+  }
+  return map
+}
+
+/** 查一条原图元数据；没有就是 `undefined`（旧数据只有一份附件时正是这种）。 */
+export function lookupOriginal(previewId, options = {}) {
+  if (typeof previewId !== 'string' || !previewId) return undefined
+  return readIndex(options).get(previewId)
+}