dsh-plugin-mobile-link 0.8.0 → 0.8.1

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

package/lib/image-variants.js

@@ -0,0 +1,315 @@
+/**
+ * 会话图片的"预览 + 可选原图"两变体能力（连接器侧）。
+ *
+ * 这一层只做三件事，且都在电脑上完成：
+ *   1. 把手机已经落盘的暂存字节交给 Host 的附件服务：预览走
+ *      `fileUploads.uploadImageStream`（Host 归一化，返回 prompt 可引用的 receipt），
+ *      原图走 `attachments.saveFileStream`（逐字节保存，不做任何重编码）。
+ *   2. 把"预览 attachmentId → 原图 file 引用"写进 Host 侧的索引
+ *      （`lib/image-originals.js`），于是重装 App / 换设备后仍能取回原图。
+ *   3. 按需把原图按区间读回给手机（元数据 + 分片），供"查看原图/保存原图"使用。
+ *
+ * 为什么不改 Host：Host 没有"按预览 id 读原图文件"的 RPC，`session/attachment`
+ * 也只认图像引用。连接的保留方法（`_link/*`）本来就是连接器自己回答的通道，
+ * 把这一段放在这里既不需要改 Host 契约，也不会新增中转的帧类型。
+ *
+ * 服务是**可选注入**：宿主缺少 `attachments` / `fileUploads`（老版本或裁剪部署）时，
+ * 三个方法都回 `link/unsupported`，手机据此显示"原图不可用"，预览仍照常工作。
+ */
+
+import { closeSync, createReadStream, openSync, readSync, statSync, unlinkSync } from 'node:fs'
+import { basename, dirname, resolve } from 'node:path'
+
+import { appendIndex, indexEntry, lookupOriginal } from './image-originals.js'
+import { dshHome } from './state.js'
+
+/** 手机侧调用的三个保留方法（`_link/` 前缀，永不转发给 Host）。 */
+export const IMAGE_COMMIT = '_link/imageCommit'
+export const IMAGE_ORIGINAL = '_link/imageOriginal'
+export const IMAGE_ORIGINAL_CHUNK = '_link/imageOriginalChunk'
+
+/** 一次分片读取的默认字节数与上限：base64 后仍远低于 32 MB 的帧上限。 */
+export const DEFAULT_CHUNK_BYTES = 512 * 1024
+export const MAX_CHUNK_BYTES = 1024 * 1024
+
+/** 手机发来的图必须落在这个目录里（`FileInbox` 的落盘位置）。 */
+function inboxDirectory(home, sessionId) {
+  return resolve(home, 'inbox', sessionId)
+}
+
+/**
+ * 交给 Host 的字节流。
+ *
+ * 挂一个空错误处理：Host 可能在读完之前就拒绝（超限、格式不接受），而我们随后会删掉
+ * 暂存文件——被丢弃的流在 unlink 之后再打开会抛 ENOENT，没人接住的 `error` 事件会变成
+ * 进程级 uncaughtException。消费方替身靠 async iterator 仍能拿到真正的失败，这里只是
+ * 保证"我们自己制造的那条尾巴"不会冒到进程上。
+ */
+function readStream(path) {
+  const stream = createReadStream(path)
+  stream.on('error', () => {})
+  return stream
+}
+
+/** 一个带稳定错误码的失败：路由把它原样翻成 `{ok:false,error}`。 */
+class ImageVariantError extends Error {
+  constructor(code, message, details = {}) {
+    super(message)
+    this.code = code
+    this.details = details
+  }
+}
+
+/** 宿主失败 → 保留方法错误码。认不出的按上传失败处理。 */
+function commitFailure(error) {
+  const code = error?.code
+  const reason = error?.details?.reason
+  if (code === 'session/not-found') return new ImageVariantError('session/not-found', '会话不存在或未挂上 Agent。')
+  if (reason === 'UNSUPPORTED_IMAGE_TYPE') {
+    return new ImageVariantError('image/unsupported-type', '这个部署不接受该图片格式。')
+  }
+  if (reason === 'IMAGE_TOO_LARGE' || reason === 'IMAGES_TOO_LARGE') {
+    return new ImageVariantError('image/too-large', '预览图超过宿主的单图上限。')
+  }
+  return new ImageVariantError('image/upload-failed', error?.message ?? String(error))
+}
+
+/** 是否是本模块回答的方法。 */
+export function isImageVariantMethod(method) {
+  return method === IMAGE_COMMIT || method === IMAGE_ORIGINAL || method === IMAGE_ORIGINAL_CHUNK
+}
+
+/** Owns the image-variant methods for one connector. */
+export class ImageVariants {
+  /**
+   * @param {object} options
+   * @param {object} [options.attachments] 宿主附件服务（`ctx.attachments`）
+   * @param {object} [options.fileUploads] 宿主上传服务（`ctx.fileUploads`）
+   * @param {object} [options.logger]
+   * @param {string} [options.home] 索引与收件箱所在的 DSH_HOME（测试注入）
+   */
+  constructor({ attachments, fileUploads, logger = console, home = dshHome() } = {}) {
+    this.attachments = attachments
+    this.fileUploads = fileUploads
+    this.logger = logger
+    this.home = home
+  }
+
+  /** 两个宿主服务都到位才答原图；缺一个就如实报不支持。 */
+  get available() {
+    return Boolean(this.attachments && this.fileUploads)
+  }
+
+  /** Answers one reserved call. Throws an `ImageVariantError` for the router to report. */
+  async handle(method, args = {}) {
+    switch (method) {
+      case IMAGE_COMMIT: return this.#commit(args)
+      case IMAGE_ORIGINAL: return this.#metadata(args)
+      case IMAGE_ORIGINAL_CHUNK: return this.#chunk(args)
+      default: throw new ImageVariantError('link/unknown-method', `unknown image method ${method}`)
+    }
+  }
+
+  /**
+   * 校验并解析一个暂存路径。
+   *
+   * 只接受收件箱的**直接子文件**：手机本来就只能把文件写进那里，
+   * 放宽到子目录或任意路径等于让手机指定电脑上的任意文件。
+   */
+  #stagedPath(rawPath, sessionId) {
+    if (typeof rawPath !== 'string' || rawPath.length === 0) {
+      throw new ImageVariantError('image/invalid-path', '缺少暂存文件路径。')
+    }
+    const resolved = resolve(rawPath)
+    if (dirname(resolved) !== inboxDirectory(this.home, sessionId)) {
+      throw new ImageVariantError('image/invalid-path', '暂存文件不在本会话的收件箱里。')
+    }
+    try {
+      if (!statSync(resolved).isFile()) throw new Error('not a file')
+    } catch {
+      throw new ImageVariantError('image/invalid-path', '暂存文件不存在。')
+    }
+    return resolved
+  }
+
+  /** 删掉本次用到的暂存文件：成品已经进了 Host 对象库，留在收件箱只会越积越多。 */
+  #discard(paths) {
+    for (const path of paths) {
+      if (!path) continue
+      try {
+        unlinkSync(path)
+      } catch {
+        /* best effort：删不掉不影响已经完成的上传 */
+      }
+    }
+  }
+
+  async #commit(args) {
+    if (!this.available) {
+      throw new ImageVariantError('link/unsupported', '这台电脑的宿主不支持图片变体上传。')
+    }
+    const sessionId = typeof args.sessionId === 'string' ? args.sessionId : ''
+    if (!sessionId) throw new ImageVariantError('session/not-found', '缺少 sessionId。')
+
+    const previewPath = args.preview ? this.#stagedPath(args.preview.path, sessionId) : undefined
+    const previewMediaType = typeof args.preview?.mediaType === 'string' && args.preview.mediaType
+      ? args.preview.mediaType
+      : 'image/jpeg'
+    const previewName = typeof args.preview?.name === 'string' && args.preview.name
+      ? basename(args.preview.name)
+      : 'image.jpg'
+
+    const originalPath = args.original ? this.#stagedPath(args.original.path, sessionId) : undefined
+    const originalName = typeof args.original?.name === 'string' && args.original.name
+      ? basename(args.original.name)
+      : basename(originalPath ?? 'original')
+    const originalMediaType = typeof args.original?.mediaType === 'string' ? args.original.mediaType : undefined
+    const sendOriginalAsFile = args.sendOriginalAsFile === true
+    if (!previewPath && !originalPath) {
+      throw new ImageVariantError('image/invalid-path', '预览与原图至少要有一份。')
+    }
+    if (sendOriginalAsFile && !originalPath) {
+      throw new ImageVariantError('image/invalid-path', '要求按文件发送原图，但没有提供原图文件。')
+    }
+    if (!previewPath && !sendOriginalAsFile) {
+      // 没有预览还能发出去的唯一形态就是"按文件发送原图"；否则用户既看不到图，
+      // 也不知道原图在哪。
+      throw new ImageVariantError('image/invalid-path', '没有预览时只能按文件发送原图。')
+    }
+
+    const discard = [previewPath, originalPath]
+    try {
+      let preview
+      if (previewPath) {
+        try {
+          preview = await this.fileUploads.uploadImageStream({
+            sessionId,
+            data: readStream(previewPath),
+            mediaType: previewMediaType,
+            name: previewName,
+          })
+        } catch (error) {
+          throw commitFailure(error)
+        }
+      }
+
+      const result = {
+        preview: preview ? { receiptId: preview.receiptId, image: preview.image } : null,
+        original: null,
+      }
+
+      if (originalPath) {
+        if (sendOriginalAsFile) {
+          // 超限或不可解码：按**文件**交回给手机，由它额外发一个 file part。
+          // 不写索引、不产生 original 变体——预览绝不会被当成原图。
+          let file
+          try {
+            file = await this.fileUploads.uploadStream({
+              sessionId,
+              data: readStream(originalPath),
+              name: originalName,
+            })
+          } catch (error) {
+            throw commitFailure(error)
+          }
+          result.fileReceiptId = file.receiptId
+          result.originalReason = typeof args.originalReason === 'string' && args.originalReason
+            ? args.originalReason
+            : 'tooLarge'
+        } else {
+          try {
+            const stored = await this.attachments.saveFileStream({
+              data: readStream(originalPath),
+              name: originalName,
+            })
+            const metadata = {
+              attachmentId: stored.attachmentId,
+              name: stored.name,
+              bytes: stored.bytes,
+              ...(originalMediaType === undefined ? {} : { mediaType: originalMediaType }),
+            }
+            if (preview) {
+              appendIndex(
+                indexEntry({ previewId: preview.image.attachmentId, original: metadata, source: 'composer' }),
+                { home: this.home, logger: this.logger },
+              )
+            }
+            result.original = metadata
+          } catch (error) {
+            // 原图存不进去不该挡下发图：预览照发，手机显示"原图不可用"。
+            this.logger.warn?.(`mobile-link: original save failed: ${error?.message ?? error}`)
+            result.originalReason = 'failed'
+          }
+        }
+      }
+
+      return result
+    } finally {
+      this.#discard(discard)
+    }
+  }
+
+  /** 原图是否存在、多大、叫什么。不读字节。 */
+  #metadata(args) {
+    const previewId = typeof args.attachmentId === 'string' ? args.attachmentId : ''
+    if (!previewId) return { available: false, reason: 'missing' }
+    const entry = lookupOriginal(previewId, { home: this.home })
+    if (!entry) return { available: false, reason: 'missing' }
+    if (!this.available) return { available: false, reason: 'unsupported' }
+    const path = this.#hostPath(entry)
+    if (!path) return { available: false, reason: 'cleaned' }
+    return { available: true, original: entry }
+  }
+
+  /** 原图对象在电脑上的路径；Host 不提供（对象已清理、提供者不支持）时返回 undefined。 */
+  #hostPath(entry) {
+    try {
+      const path = this.attachments.fileHostPath({
+        attachmentId: entry.attachmentId,
+        name: entry.name,
+        bytes: entry.bytes,
+      })
+      if (typeof path !== 'string' || !path) return undefined
+      if (!statSync(path).isFile()) return undefined
+      return path
+    } catch {
+      return undefined
+    }
+  }
+
+  /** 读原图的一个区间。只读请求的那一段，不把整文件塞进内存。 */
+  #chunk(args) {
+    const previewId = typeof args.attachmentId === 'string' ? args.attachmentId : ''
+    const entry = previewId ? lookupOriginal(previewId, { home: this.home }) : undefined
+    if (!entry) throw new ImageVariantError('image-original/missing', '没有这张图的原图。')
+    if (!this.available) throw new ImageVariantError('image-original/unsupported', '这台电脑的宿主读不到原图。')
+    const path = this.#hostPath(entry)
+    if (!path) throw new ImageVariantError('image-original/cleaned', '原图已被清理。')
+
+    const total = entry.bytes
+    const offset = Number.isFinite(args.offset) ? Math.max(0, Math.trunc(args.offset)) : 0
+    const requested = Number.isFinite(args.length) && args.length > 0
+      ? Math.trunc(args.length)
+      : DEFAULT_CHUNK_BYTES
+    const length = Math.min(requested, MAX_CHUNK_BYTES)
+    if (offset >= total) {
+      return { data: '', offset, eof: true, bytes: total }
+    }
+    const toRead = Math.min(length, total - offset)
+    const buffer = Buffer.alloc(toRead)
+    const fd = openSync(path, 'r')
+    try {
+      const read = readSync(fd, buffer, 0, toRead, offset)
+      return {
+        data: buffer.subarray(0, read).toString('base64'),
+        offset,
+        eof: offset + read >= total,
+        bytes: total,
+      }
+    } catch (error) {
+      throw new ImageVariantError('image-original/read-failed', error?.message ?? String(error))
+    } finally {
+      closeSync(fd)
+    }
+  }
+}

package/lib/index.js

@@ -32,6 +32,7 @@
 import { MobileLinkAgent } from './link.js'
 import { registerMobileLinkRoutes } from './routes.js'
 import { createHistoryService } from './history.js'
+import { ImageVariants } from './image-variants.js'
 
 /** Cordis function-plugin name (the loader row id is separate). */
 export const name = 'mobile-link'
@@ -205,6 +206,32 @@ function wireSessionQuery(ctx, history, logger) {
   }
 }
 
+/**
+ * 把宿主的附件与上传服务交给图片变体能力（**可选注入**）。
+ *
+ * 两个服务都到位才回答 `_link/image*`：预览要经 `fileUploads` 拿 prompt receipt，
+ * 原图要经 `attachments` 逐字节保存并读回。缺一个就保持"不支持"，手机显示
+ * "原图不可用"——这是如实降级，不是错误；预览仍走原有内联路径。
+ *
+ * 服务卸载（宿主换代 / 插件禁用）时把绑定摘掉，避免路由拿着失效的服务对象。
+ */
+function wireImageVariants(ctx, agent, logger) {
+  try {
+    ctx.inject(['attachments', 'fileUploads'], (scope) => {
+      const variants = new ImageVariants({
+        attachments: scope.attachments,
+        fileUploads: scope.fileUploads,
+        logger,
+      })
+      agent.setImageVariants?.(variants)
+      scope.effect?.(() => () => agent.setImageVariants?.(undefined), 'mobile-link: image variants')
+      logger.info?.('mobile-link: image variants bound to ctx.attachments / ctx.fileUploads')
+    })
+  } catch (error) {
+    logger.warn?.(`mobile-link: image variants unavailable (preview-only): ${error}`)
+  }
+}
+
 /**
  * 把宿主的任务与活会话服务交给活动名单（**可选注入**，spec 018）。
  *
@@ -225,6 +252,27 @@ function wireJobsServices(ctx, agent, logger) {
   }
 }
 
+/**
+ * 把「哪些会话值得提醒」的宿主账本交给路由（SR-02.08）。
+ *
+ * 两个服务都到位才启用过滤：`ctx.sessions` 判子会话、`ctx.workspaceRegistry` 判归档与
+ * 工作区归属。缺一个就维持旧行为（全报）——拿不到账本时把提醒全吞掉，比多报几条更难发现。
+ */
+function wireSessionScope(ctx, agent, logger) {
+  try {
+    ctx.inject(['sessions', 'workspaceRegistry'], (scope) => {
+      agent.setSessionScopeServices?.({
+        sessions: scope.sessions,
+        workspaces: scope.workspaceRegistry,
+      })
+      scope.effect?.(() => () => agent.setSessionScopeServices?.(undefined), 'mobile-link: session scope')
+      logger.info?.('mobile-link: reminders limited to formal sessions')
+    })
+  } catch (error) {
+    logger.warn?.(`mobile-link: session scope unavailable (reminders keep legacy scope): ${error}`)
+  }
+}
+
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
  * @param {Record<string, unknown>} rawConfig
@@ -241,6 +289,8 @@ export function apply(ctx, rawConfig) {
   wireEndpointResolver(ctx, agent, logger)
   wireSessionQuery(ctx, history, logger)
   wireJobsServices(ctx, agent, logger)
+  wireSessionScope(ctx, agent, logger)
+  wireImageVariants(ctx, agent, logger)
   logger.info?.(`mobile-link: ready (relay ${config.relayUrl})`)
 }
 

package/lib/journal.js

@@ -65,6 +65,8 @@ export const EVENT_KINDS = Object.freeze([
   'app.first-render',
   'app.scene',
   'app.push',
+  // §3 之后追加（2026-11-12）：一次取图在自动尝试用尽后仍失败
+  'attachment.load',
   // 内部：写失败与超大条目自报（不在契约的对外表里，但同属写入侧词表）
   'journal.error',
 ])