dsh-plugin-mobile-link 0.8.0 → 0.8.1

package/lib/handoff.js

@@ -2,7 +2,7 @@
  * 连接器写给**进程外**消费者的交接文件。
  *
  * 为什么需要它：跑在 DSH 宿主进程之外的脚本（`scripts/dev/dsh-probe.mjs`、`verify-simulator.sh`、
- * `test/tools/host.mjs` 等）与 iOS 的集成测试辅助都没有进程内上下文，拿不到注入的服务；
+ * `ios/DSHMobile/UITestHarness/host.mjs` 等）与 iOS 的集成测试辅助都没有进程内上下文，拿不到注入的服务；
  * 它们需要一个本机可读的"带凭据本机地址"。契约见
  * `specs/001-connector-host-compat/contracts/out-of-process-handoff.md`。
  *

package/lib/history/fold-summary.js

@@ -28,6 +28,9 @@
 
 import { FOLD_RECORD_TYPE, isHumanMessage } from './fold.js'
 import { bytesOf, trimRecordForWire } from './records.js'
+import {
+  isQuestionTool, questionRecordFor, resultTextOf,
+} from './question-record.js'
 import { truncateSafe } from '../unicode.js'
 
 /// `_link/hello` 声明的新能力位。老客户端不认识它，继续用 `fold: true`。
@@ -198,19 +201,7 @@ export function previewOf(args) {
   return truncateSafe(flat, SUMMARY_PREVIEW_CHARS)
 }
 
-/// 工具结果里的**正文**（与搜索的 `docText` 同一组键）。只用来量字节数，不下发。
-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')
-}
-
+/// 工具结果是否失败。正文只用来量字节数（`resultTextOf`，与作答记录共用），不下发。
 function isErrorResult(data) {
   if (data?.message?.isError === true || data?.isError === true) return true
   const error = data?.error ?? data?.message?.error
@@ -307,36 +298,54 @@ export function projectTurnUnit(events) {
   const out = []
   const summaries = []
   let group = null
+  /// 本轮的提问调用（callId → 调用信息）。跨分组保留：调用与结果之间可能夹着
+  /// 一条中间讲话，按组记账会丢掉配对。
+  const questionCalls = new Map()
+  /// 已结算、等摘要落位后再下发的记录（作答记录与图片结果，seq 升序）。
+  /// 它们都产生在过程段内部：摘要的 seq 是段起点，必须排在它们之前，
+  /// 否则一页记录会倒序。
+  let pendingRecords = []
 
   const openGroup = (event) => {
     if (group !== null) return
     group = { startSeq: event.seq, endSeq: event.seq, time: event.time, steps: [], calls: new Map() }
   }
 
+  /// 段内产生的可见记录排在它所属的过程摘要**之后**（摘要的 seq 是段起点，
+  /// 记录的是结果 seq），所以分组还开着时先攒着，flush 时一次放出。
+  const emitPending = () => {
+    if (pendingRecords.length === 0) return
+    pendingRecords.sort((lhs, rhs) => lhs.seq - rhs.seq)
+    for (const pending of pendingRecords) out.push(record(pending))
+    pendingRecords = []
+  }
+
   const flush = () => {
     const current = group
     group = null
-    if (current === null || current.steps.length === 0) return
-    const activities = countActivities(current.steps)
-    const summary = {
-      v: SUMMARY_FOLD_VERSION,
-      turn,
-      startSeq: current.startSeq,
-      endSeq: current.endSeq,
-      startedAt,
-      durationMs,
-      endReason,
-      activities,
-      groups: [{
+    if (current !== null && current.steps.length > 0) {
+      const activities = countActivities(current.steps)
+      const summary = {
+        v: SUMMARY_FOLD_VERSION,
+        turn,
         startSeq: current.startSeq,
         endSeq: current.endSeq,
-        activities: { ...activities },
-        toolCount: current.steps.filter((step) => step.kind === 'tools').length,
-        steps: current.steps,
-      }],
+        startedAt,
+        durationMs,
+        endReason,
+        activities,
+        groups: [{
+          startSeq: current.startSeq,
+          endSeq: current.endSeq,
+          activities: { ...activities },
+          toolCount: current.steps.filter((step) => step.kind === 'tools').length,
+          steps: current.steps,
+        }],
+      }
+      summaries.push(summary)
+      out.push(record({ type: FOLD_RECORD_TYPE, seq: current.startSeq, time: current.time, data: summary }))
     }
-    summaries.push(summary)
-    out.push(record({ type: FOLD_RECORD_TYPE, seq: current.startSeq, time: current.time, data: summary }))
+    emitPending()
   }
 
   for (const event of input) {
@@ -431,12 +440,36 @@ export function projectTurnUnit(events) {
         }
         group.steps.push(step)
         const callId = event?.data?.callId
-        if (typeof callId === 'string') group.calls.set(callId, step)
+        if (typeof callId === 'string') {
+          group.calls.set(callId, step)
+          if (isQuestionTool(event?.data?.name)) {
+            questionCalls.set(callId, {
+              callId,
+              name: event.data.name,
+              arguments: event.data.arguments,
+            })
+          }
+        }
         group.endSeq = event.seq
         break
       }
       case 'tool/result': {
         const callId = event?.data?.message?.toolCallId ?? event?.data?.toolCallId ?? event?.data?.callId
+        // 作答记录先取：即使结果在摘要里找不到对应步骤（调用在上一段/上一页），
+        // 已经结算的答案仍然要下发（SR-02.16）。
+        const call = questionCalls.get(callId)
+        if (call !== undefined) {
+          const question = questionRecordFor({
+            call,
+            resultText: resultTextOf(event?.data),
+            seq: event.seq,
+            time: event.time,
+          })
+          if (question !== null) {
+            if (group === null) out.push(record(question))
+            else pendingRecords.push(question)
+          }
+        }
         const step = group?.calls.get(callId)
         // 结果找不到对应调用（日志被裁剪、旧格式）就丢掉：摘要里不凭空造一步。
         if (step === undefined) break
@@ -445,6 +478,26 @@ export function projectTurnUnit(events) {
         step.resultSeq = event.seq
         if (text !== '') step.bytes = Buffer.byteLength(text, 'utf8')
         group.endSeq = event.seq
+        // A tool can deliver a picture (send_image, read_image). The process
+        // summary deliberately drops tool-result text, but dropping the image
+        // would erase the only user-visible deliverable of that turn. Keep a
+        // metadata-only result record; the client renders its image card.
+        const images = blocksOf(event).filter((block) => block?.type === 'image')
+        if (images.length > 0) {
+          pendingRecords.push({
+            type: 'tool/result',
+            seq: event.seq,
+            time: event.time,
+            data: {
+              ...(Number.isInteger(event?.data?.turn) ? { turn: event.data.turn } : {}),
+              ...(Number.isInteger(event?.data?.step) ? { step: event.data.step } : {}),
+              message: {
+                toolCallId: callId,
+                content: images.map(attachmentBlockForWire),
+              },
+            },
+          })
+        }
         break
       }
       default: {

package/lib/history/fold.js

@@ -17,6 +17,8 @@
  * （现有 `_link/sessionWindow`），取回原事件即可，不需要新端点。
  */
 
+import { questionRecordsOfEvents } from './question-record.js'
+
 /// 客户端按这个类型画过程节点；以 `+` 开头，不会与宿主事件类型相撞。
 export const FOLD_RECORD_TYPE = '+link/fold'
 
@@ -177,8 +179,16 @@ export function foldProcessRuns(records) {
   }
   flush()
 
+  // 作答记录是用户自己的输入，不是过程：折叠把它的调用与结果收进摘要后，
+  // 单独把它放回页里（SR-02.16）。按 seq 合并不是"重排页面"，而是让摘要
+  // （起点 seq）与记录（结果 seq）落在原来的先后关系上；稳定排序保证同 seq 的
+  // 两类记录不互换。
+  const merged = out
+    .concat(questionRecordsOfEvents(events).map((entry) => entry.record))
+    .sort((lhs, rhs) => lhs.seq - rhs.seq)
+
   return {
-    records: out.map((event) => ({ type: 'event', event })),
+    records: merged.map((event) => ({ type: 'event', event })),
     folds,
   }
 }

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))
+}