dsh-mobile-plugin 0.5.21 → 0.5.22

package/lib/mobile/extension-catalog.js

@@ -0,0 +1,244 @@
+'use strict';
+
+/**
+ * 已审核扩展清单：随 dsh-mobile-plugin 的 npm 包一起发布的第三方扩展（包内 `extensions/`）。
+ *
+ * 与开发包那条路的分界：开发包读作者电脑上的 `$DSH_HOME/extension-dev`（边写边看），这条读
+ * 插件包自带的只读目录 —— 只有审过、登记进 `extensions/catalog.json` 的包才下发，目录里有但
+ * 没登记的一律当不存在。审核闸门在清单，不在目录。
+ *
+ * 能力面只多「读这一个固定目录」：根由 `__dirname` 定位，不依赖进程 cwd，也不建目录；每个
+ * 文件的 size 与 sha256 由宿主扫目录现算，不信清单里写的数字。取文件先挡绝对路径与 `..` 段，
+ * 再 resolve 之后判前缀（带分隔符），不接受任意路径。仍然不暴露 shell、系统设置、任意文件读写。
+ *
+ * 坏包一律静默跳过：没登记、目录不在、manifest 读不出、超限（20MB / 200 个文件）都不该让整张
+ * 列表变红；catalog.json 不在或坏了就是一份空清单，不抛。取文件那条才逐个回错误码。
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { sendJson } = require('../shared/http-util');
+
+/** 审核清单文件名。只有列进来的 slug 才下发。 */
+const CATALOG_FILE = 'catalog.json';
+/** slug 直接当包目录名，所以只认这套字符；别的名字连读都不读。 */
+const SLUG_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** 整包上限：与开发包同一档，太重的包手机也不该整份拉。 */
+const MAX_PACKAGE_BYTES = 20 * 1024 * 1024;
+const MAX_PACKAGE_FILES = 200;
+/** 单个文件上限：一条 base64 响应要塞进手机内存，再大就不该走这条路。 */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+
+/** 包内固定目录：从 lib/mobile/ 往上两级就是包根。不依赖 cwd、不建目录（随 npm 包发布）。 */
+function catalogRoot() {
+  return path.join(__dirname, '..', '..', 'extensions');
+}
+
+/** 400 信封：与其余移动端接口同形，App 按 code 翻人话。 */
+function fail(res, status, code, message) {
+  return sendJson(res, status, { ok: false, error: { code, message } });
+}
+
+/** manifest 里取一个非空字符串，缺了 / 类型不对 / 空串都退回默认值。 */
+function textField(value, fallback) {
+  return typeof value === 'string' && value ? value : fallback;
+}
+
+/** 清单里的可选文案：非空字符串才收，其余一律 null。 */
+function textOrNull(value) {
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
+/** 能力声明收窄成字符串数组：表外的类型与空串丢掉，重复的不给第二份。 */
+function capabilitiesOf(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of value) {
+    if (typeof item !== 'string' || !item.trim() || seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+function sha256Hex(raw) {
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * 读审核清单。文件不在、读坏、形状不对都当空清单 —— 空的插件包本来就没有第三方扩展。
+ * 只收 slug / description / author / releaseNotes 四样，其余字段（包括任何 size / sha256）
+ * 一概不认：清单只负责「谁审过了」，文件事实由扫目录算。
+ */
+function readCatalog(root) {
+  let text;
+  try { text = fs.readFileSync(path.join(root, CATALOG_FILE), 'utf8'); } catch { return []; }
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return []; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray(parsed.packages)) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const raw of parsed.packages) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+    const slug = typeof raw.slug === 'string' ? raw.slug.trim() : '';
+    if (!SLUG_PATTERN.test(slug) || seen.has(slug)) continue;
+    seen.add(slug);
+    rows.push({
+      slug,
+      description: textOrNull(raw.description),
+      author: textOrNull(raw.author),
+      releaseNotes: textOrNull(raw.releaseNotes),
+    });
+  }
+  return rows;
+}
+
+/**
+ * 递归收集包内的普通文件，`path` 是相对包目录的 POSIX 路径。与 extension-dev.js 同一套口径：
+ * 点开头的文件与目录不看，符号链接不是普通文件，超限当场收手返回 false（先收完再判等于把
+ * 500MB 的目录整个哈希一遍）。
+ */
+function collectFiles(directory, acc) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!collectFiles(full, acc)) return false;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    let raw;
+    try { raw = fs.readFileSync(full); } catch { continue; }
+    acc.bytes += raw.length;
+    acc.files.push({
+      path: path.relative(acc.root, full).split(path.sep).join('/'),
+      size: raw.length,
+      sha256: sha256Hex(raw),
+    });
+    if (acc.bytes > MAX_PACKAGE_BYTES || acc.files.length > MAX_PACKAGE_FILES) return false;
+  }
+  return true;
+}
+
+/**
+ * 扫审核清单，把每个登记过、且目录与 manifest 都在的包读成一份 Package。
+ *
+ * 入口页固定是包目录下那层 `index.html`：App 侧 `extensionEntryPath` 找的就是这个名字，
+ * `manifest.json` 里写 `main` 不生效。所以这里在列包时先确认 `index.html` 真的在文件清单里，
+ * 缺了就把整包跳过 —— 装到手机上再报「需要重新安装」，比根本不出现在清单里难查得多。
+ *
+ * 纯函数、root 由调用方给：守卫拿假目录跑，线上 handler 给包内那个固定目录。
+ */
+function listPackages(root) {
+  const packages = [];
+  for (const entry of readCatalog(root)) {
+    const directory = path.join(root, entry.slug);
+    let stats;
+    try { stats = fs.statSync(directory); } catch { continue; }
+    if (!stats.isDirectory()) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(directory, 'manifest.json'), 'utf8'));
+    } catch { continue; }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) continue;
+    const acc = { root: directory, files: [], bytes: 0 };
+    if (!collectFiles(directory, acc) || acc.files.length === 0) continue;
+    if (!acc.files.some((file) => file.path === 'index.html')) continue;
+    packages.push({
+      slug: entry.slug,
+      name: textField(manifest.name, entry.slug),
+      description: entry.description,
+      author: entry.author,
+      versionName: textField(manifest.versionName, textField(manifest.version, '0.0.0')),
+      apiVersion: textField(manifest.apiVersion, textField(manifest.api_version, '1')),
+      releaseNotes: entry.releaseNotes,
+      capabilities: capabilitiesOf(manifest.capabilities),
+      size: acc.bytes,
+      fileCount: acc.files.length,
+      files: acc.files,
+    });
+  }
+  return packages;
+}
+
+/**
+ * GET /api/mobile/v1/extension/catalog（token）
+ *
+ * 回审核过的第三方扩展清单。`root` 只是给守卫传假目录的可选参数，线上由 route() 调用时
+ * 不传，永远走包内那个固定目录。
+ */
+async function handleCatalog(_ctx, _req, res, root = catalogRoot()) {
+  sendJson(res, 200, { ok: true, packages: listPackages(root) });
+}
+
+/**
+ * GET /api/mobile/v1/extension/catalog/file?slug=…&path=…（token）
+ *
+ * 取一个已审核包里的一个文件，回 base64 与 sha256（与列表里那条同一份算法）。审核闸门对取文件
+ * 同样生效：没登记进 catalog.json 的 slug 一律 404，免得绕过清单直接把目录里的字节读走。
+ *
+ * 路径检查两道：先挡明显不该出现的（绝对路径、`..` 段），再 resolve 之后判前缀 —— 后者才是
+ * 判据，前缀比较必须带分隔符，否则 `/x/extensions/foobar` 会被 `/x/extensions/foo` 认成子路径。
+ */
+async function handleCatalogFile(_ctx, req, res, root = catalogRoot()) {
+  const url = new URL(req.url || '/', 'http://x');
+  const slug = (url.searchParams.get('slug') || '').trim();
+  const requested = (url.searchParams.get('path') || '').trim();
+  if (!slug || !requested || !SLUG_PATTERN.test(slug)) {
+    return fail(res, 400, 'bad-request', '需要合法的 slug 与 path（path 是相对包目录的路径）');
+  }
+
+  if (!readCatalog(root).some((entry) => entry.slug === slug)) {
+    return fail(res, 404, 'package-missing', `审核清单里没有 ${slug} 这个包`);
+  }
+  const directory = path.join(root, slug);
+  if (!fs.existsSync(path.join(directory, 'manifest.json'))) {
+    return fail(res, 404, 'package-missing', `${slug} 没有可下发的包（缺 manifest.json）`);
+  }
+
+  if (path.isAbsolute(requested) || requested.split(/[\\/]/).includes('..')) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+  const target = path.resolve(directory, requested);
+  if (!target.startsWith(`${directory}${path.sep}`)) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+
+  let stats;
+  try { stats = fs.statSync(target); } catch { stats = null; }
+  if (!stats || !stats.isFile()) {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+  if (stats.size > MAX_FILE_BYTES) {
+    return fail(res, 413, 'file-too-large', `单个文件上限 ${MAX_FILE_BYTES} 字节，这个超了`);
+  }
+
+  let raw;
+  try { raw = fs.readFileSync(target); } catch {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+
+  const relative = path.relative(directory, target).split(path.sep).join('/');
+  sendJson(res, 200, {
+    ok: true,
+    path: relative,
+    size: raw.length,
+    sha256: sha256Hex(raw),
+    content: raw.toString('base64'),
+  });
+}
+
+module.exports = {
+  catalogRoot,
+  listPackages,
+  handleCatalog,
+  handleCatalogFile,
+  MAX_PACKAGE_BYTES,
+  MAX_PACKAGE_FILES,
+  MAX_FILE_BYTES,
+};

package/lib/mobile/local-images.js

@@ -44,7 +44,7 @@ const MEDIA_TYPES = {
   '.gif': 'image/gif',
 };
 
-/** 单张图上限：再大的东西不该整包回给手机（超出如实保持字面 markdown）。 */
+/** 单张图上限：再大的东西不该整包回给手机。 */
 const MAX_IMAGE_BYTES = 2.5 * 1024 * 1024;
 /** 读宽高只需要文件头：JPEG 的 SOF 段可能在几百字节之后，64KB 足够覆盖绝大多实拍图。 */
 const HEAD_BYTES = 64 * 1024;
@@ -246,6 +246,10 @@ async function readHead(filePath, size) {
  *
  * 编号取「路径 + 大小 + 修改时间」的短哈希：同一张图在同一轮历史里会被反复解析，
  * 这个组合稳定，且改过之后自然换号（图片内容变了本来就该换）。
+ *
+ * **超过单张上限的图也登记，只是标一句 `tooLarge`**：不登记的话正文里那一段就退回字面
+ * markdown，用户在手机上看到的是一串 `![](路径)` 源码 —— 既不知道发生过什么，也没有任何
+ * 入口。标了之后取图口如实回 413，App 画成「图片太大」的占位块，这才是用户能读懂的一句话。
  */
 async function registerLocalImage(filePath) {
   let stat;
@@ -254,7 +258,7 @@ async function registerLocalImage(filePath) {
   } catch {
     return null;
   }
-  if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_IMAGE_BYTES) return null;
+  if (!stat.isFile() || stat.size <= 0) return null;
   const id = crypto.createHash('sha1').update(`${filePath}:${stat.size}:${stat.mtimeMs}`).digest('hex').slice(0, 16);
   const known = registry.get(id);
   if (known) return { id, ...known };
@@ -262,11 +266,12 @@ async function registerLocalImage(filePath) {
   if (!head) return null;
   const mediaType = sniffMediaType(head);
   if (!mediaType) return null;
-  const parsed = imageSizeOf(head);
+  const over = stat.size > MAX_IMAGE_BYTES;
+  const parsed = over ? null : imageSizeOf(head);
   const sane = parsed && parsed.width > 0 && parsed.height > 0
     && parsed.width <= 30000 && parsed.height <= 30000;
   const size = sane ? parsed : {};
-  const entry = { filePath, mediaType, ...size };
+  const entry = { filePath, mediaType, ...size, ...(over ? { tooLarge: true } : {}) };
   registry.set(id, entry);
   while (registry.size > MAX_REGISTRY_ENTRIES) registry.delete(registry.keys().next().value);
   return { id, ...entry };
@@ -467,4 +472,4 @@ function inRanges(index, ranges) {
   return false;
 }
 
-module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf, hasRelativeImage, localImageOf, registerLocalImage, imageSizeOf, sniffMediaType, clearLocalImages };
+module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf, hasRelativeImage, localImageOf, registerLocalImage, imageSizeOf, sniffMediaType, clearLocalImages, MAX_IMAGE_BYTES };

package/lib/mobile/pet-tools.js

@@ -0,0 +1,215 @@
+'use strict';
+
+/**
+ * 给模型的两个工具：看一眼这台电脑上有哪些宠物包、做一只新的（或者改现有的）。
+ *
+ * ## 为什么要有工具
+ *
+ * 宠物包是「一个目录 + 一份 pack.json + 几张图」，而素材基本都已经是电脑上的图片文件了。
+ * 让模型自己往目录里写，它记不住放哪儿、id 什么形状、状态键叫什么；写完还得自己回一句
+ * 「好了」，用户那边刷半天也不一定看得到。工具负责的正是这几件它记不住的事。
+ *
+ * ## 为什么不收 base64 为主
+ *
+ * 与公众号那条同一个理由：让模型把几 MB 的图抄进工具参数，抄不动也抄不对。它手里真有的是
+ * 「那张图在这台电脑上的路径」，所以 `filePath` 是主路，`base64` 只在它手上真有字节时兜底。
+ *
+ * ## 能力面的边界
+ *
+ * 只碰这个库：id 形状卡死、图片只认单层 `.gif` / `.png`、单张与整包都有上限。**没有删除** ——
+ * 删是人的动作（设置页那边有个按钮），不该由模型顺手做掉。
+ */
+
+const { defineTool } = require('@deepseek-ai/dsh-tools');
+
+const {
+  listPacks,
+  writePack,
+  isImageName,
+  ID_RE,
+  KNOWN_STATES,
+} = require('./pets.js');
+
+/** 列表里一行一只：名字、id、内置还是自己做的、状态齐不齐。 */
+function packLine(pack) {
+  const tags = [pack.builtin ? '内置' : '自己做的'];
+  tags.push(`id ${pack.id}`);
+  // `pack.states` 到这一层已经是状态名数组（execute 那步折过），按名字查键永远是 undefined。
+  const missing = KNOWN_STATES.filter((state) => state !== 'sleeping' && !pack.states.includes(state));
+  tags.push(missing.length === 0 ? '五个状态都有' : `缺 ${missing.join(' / ')}（将回退到 idle）`);
+  if (pack.author) tags.push(pack.author);
+  return `· 《${pack.name}》${tags.join('，')}`;
+}
+
+/**
+ * 注册这两个工具。
+ *
+ * 必须走 `ctx.inject(['tools'], …)`：宿主里 `tools` 是子代理作用域提供的服务，插件这一层
+ * 直接读 `ctx.tools` 拿到的常常是 undefined（见 `phone/tools.js` 那一整段教训）。缺失时
+ * 静默跳过，别把整块装配掀掉。
+ */
+function installPetTools(ctx) {
+  if (typeof ctx.inject !== 'function') return;
+  try {
+    ctx.inject(['tools'], mountTools);
+  } catch (error) {
+    // 没有 tools 注入的 profile（cordis 抛 "… without inject"）：只少这两个工具，包目录与
+    // 三条路由照常可用。其余错误照抛 —— 别把真的注册失败也当成「这个 profile 没注入」。
+    const message = error && error.message ? error.message : String(error);
+    if (!message.includes('without inject')) throw error;
+  }
+}
+
+/** `ctx.inject` 的回调体。单独拎出来只为让上面那层 try/catch 短一点。 */
+function mountTools(scoped) {
+  if (!scoped || !scoped.tools || typeof scoped.tools.register !== 'function') return;
+
+  scoped.tools.register(defineTool({
+    name: 'pet_pack_list',
+    description: 'List the desktop-pet packages on this computer: the built-in ones that ship with the app, plus any the user made. Each line gives the id, name, whether it is built-in, and which animation states it has. Use this when the user asks what pets they have or what their pet looks like, and before writing a pack so you pick an id that is free.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          packs: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                builtin: { type: 'boolean' },
+                states: { type: 'array', items: { type: 'string' } },
+              },
+
+            },
+          },
+        },
+      },
+      render: (_args, value) => {
+        const packs = Array.isArray(value.packs) ? value.packs : [];
+        return [{
+          type: 'text',
+          text: packs.length === 0
+            ? '这台电脑上一个宠物包都还没有。用户想做一只的话，用 pet_pack_write 建一个。'
+            : `这台电脑上有 ${packs.length} 只：\n${packs.map(packLine).join('\n')}`,
+        }];
+      },
+    },
+    execute: async () => ({
+      packs: listPacks().map((pack) => ({
+        id: pack.id,
+        name: pack.name,
+        builtin: pack.builtin,
+        states: Object.keys(pack.states),
+      })),
+    }),
+  }));
+
+  scoped.tools.register(defineTool({
+    name: 'pet_pack_write',
+    description: 'Create or replace a desktop-pet package on this computer, so it shows up on the user\'s phone under Settings → floating pet. Use this whenever the user wants to change their pet, make a new one, or drop in their own artwork. A pack is one directory with a pack.json plus the images it references. States are idle / working / attention / done / error / sleeping, and idle is required; a state you leave out falls back to idle. Pictures are GIF (animated) or PNG (static). Give each picture the PATH of the file on this computer — the host reads it — rather than its bytes; base64 is only for when you already hold the bytes. Existing packs with the same id are replaced wholesale, including a built-in one (warn the user before doing that). You cannot delete packs; that is the user\'s job in Settings.',
+    parameters: {
+      id: {
+        type: 'string',
+        description: 'Pack id, also the folder name: 1-64 lowercase letters, digits and dashes, not starting with a dash, e.g. deepy-whale.',
+      },
+      pack: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'The whole pack.json as an object. Required keys: name and states (with at least idle). Optional: author, license, canvas {w,h}, anchor {x,baseline}, tiers.working [{min,file}] (largest min wins), loop [], sleepAfterMs. Every file named here must be one you pass in files[].',
+        properties: {
+          name: { type: 'string', description: 'Shown in the picker on the phone.' },
+          author: { type: 'string', description: 'Credited in the picker footer. Fill it in whenever the artwork is not yours.' },
+          license: { type: 'string', description: 'License note, shown next to the author.' },
+          states: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'State name → { file }. Recognised: idle, working, attention, done, error, sleeping. At least idle is required.',
+          },
+          tiers: {
+            type: 'object',
+            additionalProperties: true,
+            description: 'Optional. tiers.working is [{min, file}]: pick the image by how many conversations are running.',
+          },
+          loop: { type: 'array', items: { type: 'string' }, description: 'States that loop. Defaults to idle, working, attention.' },
+          sleepAfterMs: { type: 'number', description: 'Idle time before switching to sleeping. Only meaningful when the sleeping state exists.' },
+        },
+      },
+      files: {
+        type: 'array',
+        description: 'The images this pack uses. Each one is written into the pack folder under that name.',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string', required: true, description: 'File name inside the pack, e.g. idle.gif. Single level, .gif or .png, no slashes.' },
+            filePath: { type: 'string', description: 'Absolute path of the picture on this computer. This is the normal way.' },
+            base64: { type: 'string', description: 'The image bytes, base64 encoded. Only when you already hold the bytes and have no file to point at.' },
+          },
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          name: { type: 'string', required: true },
+          states: { type: 'array', items: { type: 'string' } },
+          written: { type: 'array', items: { type: 'string' } },
+          note: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        const lines = [`《${value.name}》存好了，id ${value.id}，状态：${(value.states || []).join(' / ') || 'idle'}。`];
+        if (Array.isArray(value.written) && value.written.length > 0) lines.push(`图片已存：${value.written.join('、')}。`);
+        if (value.note) lines.push(value.note);
+        return [{ type: 'text', text: lines.join('\n') }];
+      },
+    },
+    execute: async (args) => {
+      const id = typeof args.id === 'string' ? args.id.trim() : '';
+      if (!ID_RE.test(id)) {
+        throw new Error(`"${id}" 不是合法的宠物包 id：只认 1-64 位小写字母、数字与连字符，且不以连字符开头。`);
+      }
+      // 文件名先收窄一遍再交给库：这样「哪几个名字不合规矩」能在写之前就一趟说清。
+      const files = Array.isArray(args.files) ? args.files : [];
+      const badNames = files
+        .map((item) => (item && typeof item.path === 'string' ? item.path.trim() : ''))
+        .filter((name) => !isImageName(name));
+      if (badNames.length > 0) {
+        throw new Error(`这几个文件名不合规矩：${badNames.map((name) => `"${name}"`).join('、')}。只认单层 .gif / .png（不含斜杠），例如 idle.gif。`);
+      }
+
+      let result;
+      try {
+        result = await writePack({ id, pack: args.pack, files });
+      } catch (error) {
+        throw new Error(error && error.message ? error.message : '没能写进去。');
+      }
+      const { pack, rejected, written, overriddenBuiltin } = result;
+      const notes = [];
+      if (overriddenBuiltin) {
+        notes.push(`这个 id 原本有一只内置的宠物，现在被这份盖住了（手机上显示的是新的这只）。内置那份没被改动。`);
+      }
+      if (rejected.length > 0) {
+        notes.push(`这几张没能收进来：${rejected.join('、')}（读不到，或者不是 .gif / .png）。`);
+      }
+      return {
+        id: pack.id,
+        name: pack.name,
+        states: Object.keys(pack.states),
+        written,
+        ...(notes.length > 0 ? { note: notes.join('\n') } : {}),
+      };
+    },
+  }));
+}
+
+module.exports = { installPetTools };