dsh-mobile-plugin 0.5.24 → 0.5.27

package/lib/mobile/phone-knowledge.js

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * 用法知识库：把 `knowledge/apps/*.md` 与 `knowledge/sites/*.md` 读进来。
+ * App 那条按前台包名匹配一段说明，网站那条按当前网页地址（主机名）匹配。
+ *
+ * 知识只讲事实（这个 App / 网站是什么、界面怎么组织、有哪些功能、有哪些容易混淆的入口），
+ * 不写行为规则 —— 该不该做、要不要确认是审批层的事，写进知识里就会和审批层打架。
+ *
+ * 两条设计取舍：
+ * - **按 mtime 缓存**：目录里十几份小文件，每次读屏都重读一遍纯属浪费；mtime 没变就用上一份。
+ * - **加载失败安静退化**：知识库目录不存在、某个文件读坏了，都只当这一条没有，绝不抛异常。
+ *   知识是锦上添花，不能因为它把整个插件装载掀翻。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** 知识库根目录：本文件在 lib/mobile/ 下，往上是插件根。 */
+const KNOWLEDGE_ROOT = path.join(__dirname, '..', '..', 'knowledge');
+
+/** 默认 App / 网站知识目录。 */
+const DEFAULT_DIR = path.join(KNOWLEDGE_ROOT, 'apps');
+const DEFAULT_SITES_DIR = path.join(KNOWLEDGE_ROOT, 'sites');
+
+/** filePath -> { mtimeMs, doc }。文件没改就不重读。 */
+const cache = new Map();
+
+/** sessionId -> Set<知识条目名>。同一个对话、同一个 App 只附一次。 */
+const noted = new Map();
+
+/**
+ * App 知识目录。允许用环境变量覆盖，方便测试「目录不存在时返回空」这条退化路径。
+ */
+function knowledgeDir() {
+  const override = process.env.DSH_PHONE_KNOWLEDGE_DIR;
+  if (typeof override === 'string' && override.trim()) return override.trim();
+  return DEFAULT_DIR;
+}
+
+/**
+ * 网站知识目录。优先用 `DSH_PHONE_SITES_DIR` 覆盖；没有时按 App 目录的同级 `sites`
+ * 推（App 目录被 `DSH_PHONE_KNOWLEDGE_DIR` 指到别处时，网站跟着它的兄弟目录走），
+ * 否则用插件自带的 `knowledge/sites`。
+ */
+function sitesDir() {
+  const explicit = process.env.DSH_PHONE_SITES_DIR;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+  const appsOverride = process.env.DSH_PHONE_KNOWLEDGE_DIR;
+  if (typeof appsOverride === 'string' && appsOverride.trim()) {
+    return path.join(path.dirname(appsOverride.trim()), 'sites');
+  }
+  return DEFAULT_SITES_DIR;
+}
+
+/** 把一段 `["a","b"]` 或普通标量解析成数组。解析不了就当空数组。 */
+function toArray(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item));
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  return [];
+}
+
+/** 去掉两端成对的引号。 */
+function unquote(text) {
+  if (text.length >= 2) {
+    const first = text[0];
+    const last = text[text.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) return text.slice(1, -1);
+  }
+  return text;
+}
+
+/**
+ * 解析一份知识文件：frontmatter 进字段，剩下的是正文。
+ *
+ * 只认简单的一层 `key: value`，够用了；数组用 JSON（`["com.tencent.mm"]`），
+ * 与 Mika 的 APP.md 写法一致。解析不出来的键就留默认值，不抛。
+ */
+function parseDoc(filePath, text) {
+  const meta = {};
+  let body = typeof text === 'string' ? text : '';
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(body);
+  if (match) {
+    const raw = match[1];
+    body = match[2] || '';
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const idx = trimmed.indexOf(':');
+      if (idx < 0) continue;
+      const key = trimmed.slice(0, idx).trim();
+      let value = trimmed.slice(idx + 1).trim();
+      if (value.startsWith('[')) {
+        try {
+          value = JSON.parse(value);
+        } catch {
+          value = [];
+        }
+      } else {
+        value = unquote(value);
+      }
+      if (key) meta[key] = value;
+    }
+  }
+  return {
+    name: typeof meta.name === 'string' ? meta.name : '',
+    display: typeof meta.display === 'string' ? meta.display : '',
+    description: typeof meta.description === 'string' ? meta.description : '',
+    packages: toArray(meta.packages),
+    sites: toArray(meta.sites),
+    aliases: toArray(meta.aliases),
+    open: typeof meta.open === 'string' ? meta.open : '',
+    pace: typeof meta.pace === 'string' ? meta.pace : '',
+    body: body.trim(),
+    file: path.basename(filePath),
+  };
+}
+
+/**
+ * 读出某个目录下的全部知识条目（带正文，供匹配和守卫使用）。目录不存在或读不了就返回空数组。
+ *
+ * `dir` 缺省是 App 目录；网站知识传 `sitesDir()`。缓存按完整文件路径做键，两个目录互不干扰，
+ * 清缓存时也只清这个目录下的，不会把另一个目录的缓存顺手删掉。
+ */
+function loadDocs(dir = knowledgeDir()) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    // 目录不存在：只清这个目录前缀下的缓存，别误删别的目录的。
+    for (const key of [...cache.keys()]) if (key.startsWith(dir + path.sep)) cache.delete(key);
+    return [];
+  }
+  const seen = new Set();
+  const docs = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
+    const filePath = path.join(dir, name);
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    seen.add(filePath);
+    const hit = cache.get(filePath);
+    if (hit && hit.mtimeMs === stat.mtimeMs) {
+      docs.push(hit.doc);
+      continue;
+    }
+    try {
+      const text = fs.readFileSync(filePath, 'utf8');
+      const doc = parseDoc(filePath, text);
+      cache.set(filePath, { mtimeMs: stat.mtimeMs, doc });
+      docs.push(doc);
+    } catch {
+      // 单个文件读坏了只算它没有，其余照常。
+    }
+  }
+  for (const key of [...cache.keys()]) {
+    if (key.startsWith(dir + path.sep) && !seen.has(key)) cache.delete(key);
+  }
+  docs.sort((a, b) => (a.name || a.file).localeCompare(b.name || b.file));
+  return docs;
+}
+
+/** 列出知识库里的所有 App（不带正文）。 */
+function listApps() {
+  return loadDocs().map((doc) => ({
+    name: doc.name,
+    display: doc.display,
+    packages: doc.packages.slice(),
+    aliases: doc.aliases.slice(),
+    open: doc.open,
+  }));
+}
+
+/**
+ * 按包名或别名找到一条知识。包名精确匹配优先（忽略大小写），其次才看别名。
+ * 找不到返回 null。
+ */
+function matchApp(packageName) {
+  const pkg = typeof packageName === 'string' ? packageName.trim() : '';
+  if (!pkg) return null;
+  const needle = pkg.toLowerCase();
+  const docs = loadDocs();
+  const byPackage = docs.find((doc) => doc.packages.some((item) => item.toLowerCase() === needle));
+  if (byPackage) return byPackage;
+  const byAlias = docs.find((doc) => doc.aliases.some((item) => item.toLowerCase() === needle));
+  return byAlias || null;
+}
+
+/** 按包名或别名匹配，返回它的正文；匹配不到返回空串。 */
+function matchByPackage(packageName) {
+  const doc = matchApp(packageName);
+  return doc && doc.body ? doc.body : '';
+}
+
+/** 列出知识库里的所有网站（不带正文）。 */
+function listSites() {
+  return loadDocs(sitesDir()).map((doc) => ({
+    name: doc.name,
+    display: doc.display,
+    description: doc.description,
+    sites: doc.sites.slice(),
+    aliases: doc.aliases.slice(),
+  }));
+}
+
+/** 从一段地址里抽出主机名（小写）。认不出就退回按 `/`、`:` 切的第一段。 */
+function hostOf(raw) {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (!text) return '';
+  try {
+    const url = new URL(text.includes('://') ? text : `https://${text}`);
+    return url.hostname.toLowerCase();
+  } catch {
+    return text.toLowerCase().split('/')[0].split(':')[0];
+  }
+}
+
+/** 归一化站点条目：去协议、去路径、去开头的 www.。 */
+function normalizeSite(site) {
+  return String(site || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, '')
+    .replace(/\/.*$/, '')
+    .replace(/^www\./, '');
+}
+
+/**
+ * 按当前网页地址找到一条网站知识。主机名匹配：完全相等，或是它的子域（`www.youtube.com`
+ * 命中 `youtube.com`）。一条都没有时再退回按别名匹配整段输入。找不到返回 null。
+ */
+function matchSite(url) {
+  const host = hostOf(url);
+  if (!host) return null;
+  const docs = loadDocs(sitesDir());
+  const hit = docs.find((doc) => doc.sites.some((site) => {
+    const s = normalizeSite(site);
+    if (!s) return false;
+    return host === s || host === `www.${s}` || host.endsWith(`.${s}`);
+  }));
+  if (hit) return hit;
+  const needle = typeof url === 'string' ? url.trim().toLowerCase() : '';
+  if (!needle) return null;
+  return docs.find((doc) => doc.aliases.some((alias) => alias.toLowerCase() === needle)) || null;
+}
+
+/** 按网址匹配，返回它的正文；匹配不到返回空串。 */
+function matchBySite(url) {
+  const doc = matchSite(url);
+  return doc && doc.body ? doc.body : '';
+}
+
+/**
+ * 给某个对话附一次某个 App 的正文。同一个 sessionId + 同一个 App 只返回一次，之后返回空串。
+ * sessionId 或包名为空、匹配不到、正文为空，都返回空串。
+ */
+function noteFor(sessionId, packageName) {
+  const sid = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (!sid) return '';
+  const doc = matchApp(packageName);
+  if (!doc || !doc.body) return '';
+  let set = noted.get(sid);
+  if (!set) {
+    set = new Set();
+    noted.set(sid, set);
+  }
+  const key = doc.name || doc.file;
+  if (set.has(key)) return '';
+  set.add(key);
+  return doc.body;
+}
+
+/** 测试用：清掉「已经附过」的账本。 */
+function resetNotes() {
+  noted.clear();
+}
+
+/** 测试用：丢掉 mtime 缓存，强制下次重读。 */
+function resetCache() {
+  cache.clear();
+}
+
+module.exports = {
+  knowledgeDir,
+  sitesDir,
+  loadDocs,
+  listApps,
+  listSites,
+  matchApp,
+  matchByPackage,
+  matchSite,
+  matchBySite,
+  noteFor,
+  resetNotes,
+  resetCache,
+};

package/lib/mobile/schedule.js

@@ -24,13 +24,14 @@ const SCHEDULE_ID_MAX = 200;              // 任务 id / messageId 长度上限
 const SCHEDULE_TITLE_MAX = 200;           // 任务标题
 const SCHEDULE_PROMPT_MAX = 4000;         // prompt（列表里只用于预览）
 const SCHEDULE_EXPRESSION_MAX = 200;      // cron 五段表达式
+const SCHEDULE_RRULE_MAX = 1000;          // rrule 两行（DTSTART + RRULE）
 const SCHEDULE_TIMEZONE_MAX = 64;         // IANA 时区名
 const SCHEDULE_TIME_MAX = 40;             // HH:mm:ss.SSS 与 RFC3339 时间戳
 const SCHEDULE_DEFAULT_LIMIT = 20;        // 历史记录默认条数
 const SCHEDULE_MAX_LIMIT = 100;           // 历史记录条数上限（宿主同一口径）
 
-/** 宿主 ScheduleRecord 的封闭 kind 集。 */
-const SCHEDULE_KINDS = new Set(['after', 'at', 'every', 'daily', 'weekly', 'cron']);
+/** 宿主 ScheduleRecord 的封闭 kind 集（`rrule` 是 v2 宿主加的）。 */
+const SCHEDULE_KINDS = new Set(['after', 'at', 'every', 'daily', 'weekly', 'cron', 'rrule']);
 
 /** 宿主没有这个服务时对 App 的统一回答（不是「没有任务」）。 */
 const UNAVAILABLE = Object.freeze({
@@ -106,6 +107,32 @@ function normalizeLastDelivery(value) {
   return { scheduledAt, deliveredAt };
 }
 
+/**
+ * 一条任务属于哪个会话。
+ *
+ * v2 宿主把它挪进了 `target`（`session` / `new_once` 带 `sessionId`，`new` 没有），v1 才有行上的
+ * `sessionId`；`involvedSessionIds` 是参与过这条任务的会话（建它的那个在前），单会话任务通常就
+ * 一条。三处依次退，第一个非空的就是它 —— `new` 目标没有确定会话，退回参与过的那条，
+ * 否则这条任务在手机上永远筛不出来（手机是按会话筛的）。
+ */
+function entrySessionId(item) {
+  const direct = requiredText(item.sessionId, SCHEDULE_ID_MAX);
+  if (direct) return direct;
+  const target = item.target;
+  if (target && typeof target === 'object' && !Array.isArray(target)) {
+    const scoped = requiredText(target.sessionId, SCHEDULE_ID_MAX);
+    if (scoped) return scoped;
+  }
+  const involved = item.involvedSessionIds;
+  if (Array.isArray(involved)) {
+    for (const candidate of involved) {
+      const resolved = requiredText(candidate, SCHEDULE_ID_MAX);
+      if (resolved) return resolved;
+    }
+  }
+  return '';
+}
+
 /**
  * 把一条宿主任务压成手机认的 `ScheduleEntry`。
  *
@@ -122,8 +149,8 @@ function normalizeScheduleEntry(item, sessionId, state) {
   if (typeof item.kind !== 'string' || !SCHEDULE_KINDS.has(item.kind)) return null;
   const title = requiredText(item.title, SCHEDULE_TITLE_MAX);
   if (!title) return null;
-  // catalog 的 sessionId 在行上，list 的行上没有（由查询串那个顶上）。
-  const resolvedSessionId = sessionId || requiredText(item.sessionId, SCHEDULE_ID_MAX);
+  // catalog 的会话归属在 target / involvedSessionIds 上，list 的由查询串那个顶上。
+  const resolvedSessionId = sessionId || entrySessionId(item);
   if (!resolvedSessionId) return null;
 
   const entry = {
@@ -144,6 +171,16 @@ function normalizeScheduleEntry(item, sessionId, state) {
       if (item.kind === 'after') entry.afterSeconds = seconds;
       else entry.everySeconds = seconds;
     }
+  } else if (item.kind === 'rrule') {
+    // `rrule` 自己带时区（`DTSTART;TZID=Asia/Shanghai:…`），行上没有单独那一格；规则整段
+    // 转给 App，时区顺手从 DTSTART 里取出来补上，详情页那一行才不是空的。
+    const rrule = optionalText(item.rrule, SCHEDULE_RRULE_MAX);
+    if (rrule !== undefined) {
+      entry.rrule = rrule;
+      const zone = /^DTSTART;TZID=([^:]+):/m.exec(rrule);
+      const timeZone = zone === null ? undefined : optionalText(zone[1], SCHEDULE_TIMEZONE_MAX);
+      if (timeZone !== undefined) entry.timeZone = timeZone;
+    }
   } else if (item.kind !== 'at') {
     // `at` 没有专有字段，别把宿主残留的 time / expression 顺手转发出去。
     const time = optionalText(item.time, SCHEDULE_TIME_MAX);
@@ -186,9 +223,15 @@ function normalizeScheduleEntries(value, sessionId, state) {
   return out;
 }
 
-/** 宿主的 `status` → 手机认的 `state`。缺字段时按 active：宁可多显示一条，别整条消失。 */
+/**
+ * 宿主的 `status` → 手机认的 `state`。
+ *
+ * v1 只有 `active` / `inactive`；v2 拆成 `active` / `paused` / `ended` —— 后两个都不是
+ * 「还会继续投递」，手机那一页只有两档筛选，都收进 `inactive`。缺字段时按 active：
+ * 宁可多显示一条，别整条消失。
+ */
 function stateOf(status) {
-  return status === 'inactive' ? 'inactive' : 'active';
+  return status === 'inactive' || status === 'paused' || status === 'ended' ? 'inactive' : 'active';
 }
 
 /** 错误文字：宿主 reject 的原文，取不到就退回 String()，别回一句空话。 */
@@ -372,6 +415,20 @@ async function handleScheduleHistory(ctx, req, res) {
   });
 }
 
+/**
+ * 删一条任务。
+ *
+ * v1 宿主有独立的 `delete({sessionId, id})`；v2 把它并进了 `edit({id, action:'delete'})`
+ * —— 后者只认 id，存储本来就是全局一张表，行上的 sessionId 只是字段（见 A2-57 的坑）。
+ * 先问 `edit`，宿主没有这个方法再退回老的 `delete`。
+ */
+async function deleteTask(service, sessionId, id) {
+  if (typeof service.edit === 'function') {
+    return service.edit({ id, action: 'delete' });
+  }
+  return service.delete({ sessionId, id });
+}
+
 /** POST /api/mobile/v1/schedule/delete —— body { sessionId, id }。 */
 async function handleScheduleDelete(ctx, req, res) {
   const body = (await readJsonBody(req)) || {};
@@ -386,7 +443,7 @@ async function handleScheduleDelete(ctx, req, res) {
 
   let value;
   try {
-    value = await service.delete({ sessionId, id });
+    value = await deleteTask(service, sessionId, id);
   } catch (error) {
     return sendFailure(res, error);
   }

package/lib/mobile/sessions.js

@@ -14,6 +14,8 @@
  * 所以 lib/mobile 下的 import 路径一行都不用改。
  */
 
+const path = require('node:path');
+
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { isFreshRequest } = require('../shared/fresh-request');
 const { listRevision, unchangedListBody } = require('../shared/list-revision.js');
@@ -23,6 +25,7 @@ const { withIdempotency, requestIdOf } = require('./idempotency.js');
 const { listTitle, deriveMessages, lastMessageOf, promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
+const { workspaceRoots, isWithin } = require('./allowed-zone.js');
 const {
   canonicalDeviceKey, sessionListResponseState, invalidateSessionList, deletedSessionIdsOf,
   completionGenerationOf, bumpCompletionGeneration,
@@ -336,21 +339,53 @@ async function handleStats(ctx, req, res) {
  * 的 sessionIds 账上，桌面端侧栏项目下立即可见；无 workspaceId 时回退 cwd
  * （不传则归属其默认/未分组工作区）。
  * 走宿主 apiProxy 的 session.create（接受 workspaceId 或 cwd，二者不能同时给）。
+ *
+ * cwd 进来之前必须落在**宿主已登记的工作区**里：会话的 cwd 就是 allowed-zone 的第二个
+ * 根（见 allowed-zone.js 的 allowedRoots），随手塞一个 `/` 进来等于把整台机器变成
+ * 「允许读写区」。工作区清单读不到时照实回 502，不按「没有工作区」处理 —— 那会让每个
+ * 目录都变成 403，用户看到的是「我的目录突然不能用了」。
  */
 async function handleNew(ctx, req, res) {
   const body = await readJsonBody(req, 64 * 1024);
+  const workspaceId = body && typeof body.workspaceId === 'string' && body.workspaceId.trim()
+    ? body.workspaceId.trim()
+    : '';
+  // 只有走 cwd 那条路才需要校验：workspaceId 本身就把范围交给了宿主登记过的那一项。
+  let cwd = '';
+  if (!workspaceId && body && typeof body.cwd === 'string' && body.cwd.trim()) {
+    const declared = body.cwd.trim();
+    if (!path.isAbsolute(declared)) {
+      return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'cwd 必须是绝对路径' } });
+    }
+    cwd = path.resolve(declared);
+    let roots;
+    try {
+      roots = await workspaceRoots(ctx);
+    } catch (error) {
+      return sendJson(res, 502, {
+        ok: false,
+        error: {
+          code: (error && error.code) || 'workspace-list-failed',
+          message: String((error && error.message) || error),
+        },
+      });
+    }
+    if (!roots.some((root) => isWithin(root, cwd))) {
+      return sendJson(res, 403, {
+        ok: false,
+        error: { code: 'outside-allowed', message: '这个目录不在能建会话的范围里（只能落在已登记的工作区）' },
+      });
+    }
+  }
   // 新建会话是**非幂等**写：同一发请求被重投一次就会凭空多一个会话。requestId 由
   // App 在构造请求头时生成一次，内核换通道重投复用同一个 init（同一个头），重投于是
   // 命中这里、直接拿回第一次的 sessionId（见 mobile/idempotency.js）。
   const outcome = await withIdempotency(ctx, canonicalDeviceKey(req), requestIdOf(req, body), async () => {
     let payload = {};
-    const workspaceId = body && typeof body.workspaceId === 'string' && body.workspaceId.trim()
-      ? body.workspaceId.trim()
-      : '';
     if (workspaceId) {
       payload.workspaceId = workspaceId;
-    } else if (body && typeof body.cwd === 'string' && body.cwd.trim()) {
-      payload.cwd = body.cwd.trim();
+    } else if (cwd) {
+      payload.cwd = cwd;
     }
     // 宿主 session.create 接受 agentPreset：新建时直接定档，省掉「先建再 select」的
     // 两步（select 只在会话还没开跑时生效，新建后立刻 select 同样可行但多一次 RPC）。

package/lib/mobile/wechat.js

@@ -426,6 +426,27 @@ function mediaTypeOf(name, bytes) {
   return 'image/png';
 }
 
+/**
+ * HTTP 那条路上，图片只留 `{name, base64}` 两个字段 —— `path`（以及任何路径形式的字段）一律剥掉。
+ *
+ * 为什么 HTTP 这条路不收 path：这个请求来自手机，手机口中的「本机路径」指的是手机上的文件；
+ * 宿主却跑在另一台电脑上，照着这个名字去读，读到的是电脑上同名的任意文件 —— 一次保存就顺走
+ * 了宿主机上任何一张图。工具那一侧不经过这里：模型自己有读盘权，给的路径本来就该能读，所以
+ * `writeArticle` / `mediaBytesOf` 的 path 能力原样保留。
+ *
+ * 只认 name 与 base64，别的字段（path、filePath、localPath、src……）自然全丢；`images` 不是
+ * 数组、项不是对象都按「没给」处理，不抛。name 合不合规矩交给 `writeArticle` 现有的拒绝逻辑。
+ */
+function httpImagesOnly(images) {
+  if (!Array.isArray(images)) return [];
+  const out = [];
+  for (const item of images) {
+    if (!isRecord(item)) continue;
+    out.push({ name: item.name, base64: item.base64 });
+  }
+  return out;
+}
+
 /**
  * `POST /wechat/article` —— 写一篇（App 侧目前不用，留给「在手机上删 / 改名」这类动作；
  * AI 那条路走的是工具，见 `tools.js`）。
@@ -433,8 +454,10 @@ function mediaTypeOf(name, bytes) {
 async function handleArticleWrite(_ctx, req, res) {
   const body = await readJsonBody(req, 8 * 1024 * 1024);
   if (!isRecord(body)) return fail(res, 400, 'bad-request', '请求体不是对象。');
+  // 只让 HTTP 入口不收 path：图片只留 {name, base64}（见 httpImagesOnly）。
+  const input = { ...body, images: httpImagesOnly(body.images) };
   try {
-    const { article } = await writeArticle(body);
+    const { article } = await writeArticle(input);
     sendJson(res, 200, {
       ok: true,
       id: article.id,
@@ -479,6 +502,8 @@ module.exports = {
   handleArticleDelete,
   // 工具那一侧直接用这几个（不经过 HTTP）
   writeArticle,
+  // 纯函数：HTTP 入口剥 path 用，单独导出便于直接测
+  httpImagesOnly,
   readArticle,
   listArticles,
   plainTextOf,

package/lib/p2p/rendezvous.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * 点对点隧道的**会合**：手机把自己的打洞候选报上来，电脑按它把自己那半边拉起来，
+ * 再把电脑自己的候选还回去。
+ *
+ * 为什么需要这一步：打洞的本质是「两端同时往对方的出口地址发包」。手机上知道自己的
+ * 出口（它自己问 STUN），电脑也知道自己的；但**彼此不知道对方的**。没有这一次交换，
+ * 两边都只能往空气里打 —— 这正是这条通道早先一次也连不上的原因。
+ *
+ * 为什么走这条路而不是另架一个会合服务：这一发就打在我们**已经有**的那条链路上（局域网 /
+ * 中转 / tailcat 隧道），只传几十个字节的地址。它不承载业务数据，也不新增任何部署物 ——
+ * 与「用户没有服务器、我们也不提供」是同一条原则。真正的数据面完全在两端之间。
+ *
+ * 端点本身是幂等的：手机每次心跳都可以带上当前候选再来一次，电脑发现「我已经按这份候选
+ * 起来过了」就直接复用，不重新打洞（重打会让已经打通的洞白丢一次）。
+ */
+
+const { sendJson } = require('../http/routing.js');
+const { readJsonBody } = require('../shared/http-util.js');
+
+/** 候选白名单：只收 `ip:port` 形状，长度也限住 —— 对端给的任何东西都当不可信数据。 */
+const CANDIDATE = /^[0-9a-fA-F.:[\]]{3,64}$/;
+
+/** 手机的公钥：只认 base64（44 字符）或 hex（64 字符）两种，长度不等就不是密钥。 */
+const PUBLIC_KEY = /^[A-Za-z0-9+/=]{43,44}$|^[0-9a-fA-F]{64}$/;
+
+function normalizePublicKey(value) {
+  if (typeof value !== 'string') return '';
+  const text = value.trim();
+  return PUBLIC_KEY.test(text) ? text : '';
+}
+
+function normalizeCandidates(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const item of list) {
+    if (typeof item !== 'string') continue;
+    const text = item.trim();
+    if (!text || text.length > 64 || !CANDIDATE.test(text)) continue;
+    if (!out.includes(text)) out.push(text);
+    // 上限 16 条：正常也就两三条，多出来的只可能是拼错的输入。
+    if (out.length >= 16) break;
+  }
+  return out;
+}
+
+/**
+ * @param {object} deps
+ * @param {object} deps.p2p 装配层交下来的 P2P 门面（`lib/p2p/wiring.cjs`）
+ * @param {() => number} [deps.lanPortInUse] 本机插件端口（隧道里那些连接最终转给它）
+ */
+function createP2PRendezvousHandler(deps) {
+  /**
+   * 隧道里进来的连接该转到哪个本机端口。
+   *
+   * 会话门面自己知道（`lib/p2p/wiring.cjs` 的 `targetPort`：局域网开着转局域网端口、
+   * 关着转宿主 web 端口）。门面没给时才退回 `lanPortInUse` —— 那是老形状，局域网关着时
+   * 指向一个没人听的口，隧道会「连上了却毫无反应」。
+   */
+  const targetPortOf = () => {
+    const door = deps.p2p;
+    if (door && typeof door.targetPort === 'function') return Number(door.targetPort()) || 0;
+    return typeof deps.lanPortInUse === 'function' ? deps.lanPortInUse() : 0;
+  };
+  return async function handleRendezvous(_ctx, req, res) {
+    if (!deps.p2p || typeof deps.p2p.open !== 'function') {
+      // 这台电脑没装助手 / 没起这条通道：如实说，手机那边据此把这一条标成不可用，
+      // 而不是一直等一个永远不会来的回答。
+      sendJson(res, 200, { ok: true, available: false, reason: 'p2p-unavailable' });
+      return;
+    }
+
+    const body = await readJsonBody(req, 16 * 1024);
+    const candidates = normalizeCandidates(body && body.candidates);
+    const localCandidates = normalizeCandidates(body && body.localCandidates);
+    // 手机自己的公钥：电脑拉起隧道时要拿它对 WireGuard 握手。没有它，电脑配不出对端，
+    // 这条通道根本起不来（不是「打洞打不通」，是连设备都配不上）。
+    const phonePublicKey = normalizePublicKey(body && body.phonePublicKey);
+    // 手机候选为空也允许：电脑照样能「只听不打」地起来、把自己的候选报回去，等手机来打。
+    // 硬要它先有候选，等于把「谁先拨」的顺序焊死，第一发永远没有候选。
+
+    const opened = await deps.p2p.open({
+      // **不转 `body.peerKey`**：手机那一格装的是**我这台电脑的公钥**（它拿它确认「对面是那台
+      // 电脑」），不是它自己的。会话要的对端是手机那把，只有 `phonePublicKey` 一处。
+      // 早先把这一格直接当对端传下去，电脑于是拿自己的公钥配 WireGuard —— 洞能开、`path`
+      // 报 `direct`，但握手永远对不上，数据面一个包都过不去。
+      phonePublicKey,
+      candidates,
+      localCandidates,
+      targetPort: targetPortOf(),
+    });
+    if (!opened || opened.ok === false) {
+      sendJson(res, 200, {
+        ok: true,
+        available: false,
+        reason: (opened && opened.code) || 'start-failed',
+      });
+      return;
+    }
+
+    // 回我自己的候选：手机拿到这份，才知道往哪打。
+    sendJson(res, 200, {
+      ok: true,
+      available: true,
+      // 隧道里那个固定端口（手机拨它）。
+      port: deps.p2p.constants ? deps.p2p.constants.P2P_PORT : undefined,
+      // **我这一把公钥**：手机要拿它确认「对面是那台电脑」并配 WireGuard 对端。二维码里
+      // 有这一份，但已经配过对、或换过电脑的老会话也得能自己拿到 —— 否则手机只能重新扫码。
+      publicKey: typeof opened.publicKey === 'string' ? opened.publicKey : '',
+      // 电脑的出口地址（STUN 那份 + 本机私网那份）。**这一份才是打洞的起点**。
+      candidates: normalizeCandidates(opened.candidates),
+      localCandidates: [],
+    });
+  };
+}
+
+module.exports = { createP2PRendezvousHandler, normalizeCandidates };