dsh-mobile-plugin 0.2.0 → 0.2.2

package/lib/mobile/relay-control.js

@@ -75,6 +75,7 @@ function configView(state) {
     lanPort: Number.isInteger(state.lanPort) ? state.lanPort : 18787,
     pairingPolicy: pairingApproval.normalize(state.pairingPolicy),
     preferredLanAddress: typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : '',
+    manualLanUrl: typeof state.manualLanUrl === 'string' ? state.manualLanUrl : '',
     /** 注册密钥设没设（值本身不回）。 */
     registerSecretSet: typeof state.registerSecret === 'string' && state.registerSecret !== '',
   };
@@ -129,6 +130,16 @@ function configPatch(body) {
     }
     patch.preferredLanAddress = body.preferredLanAddress.trim();
   }
+  // 用户手填的直连地址：**空串是合法值**（= 清掉这条，回到只认网卡候选）。
+  // 与 `relayUrl` 一样只挡类型与长度，格式由 `relay/lan-network.cjs` 的 `manualCandidate`
+  // 在产候选那一步判 —— 这里拒掉一条「看着不像地址」的字符串，只会让手机上那句错误提示
+  // 指向一个它自己也说不清的规则。
+  if (body.manualLanUrl !== undefined) {
+    if (typeof body.manualLanUrl !== 'string' || body.manualLanUrl.length > 200) {
+      return { ok: false, message: '直连地址必须是 200 字以内的字符串（空串表示清掉）' };
+    }
+    patch.manualLanUrl = body.manualLanUrl.trim().replace(/\/+$/, '');
+  }
   if (Object.keys(patch).length === 0) return { ok: false, message: '没有任何可改的字段' };
   return { ok: true, patch };
 }
@@ -194,6 +205,8 @@ function createRelayControlHandlers(deps) {
       lan: lanCandidates(port),
       public: publicCandidates(port),
       ipv6: ipv6Candidates(port),
+      /** 用户手填的那条直连地址（空串 = 没填）。与上面三份并列给出，界面不用拼。 */
+      manual: typeof state.manualLanUrl === 'string' ? state.manualLanUrl : '',
     };
   }
 

package/lib/mobile/session-cache.js

@@ -39,7 +39,8 @@ const lastTurnFacts = new WeakMap();
 // Prevent duplicate prompt calls when a mobile request is retried after a timeout.
 const sendIdempotency = new WeakMap();
 // 写操作（新建/改名/归档/分叉）的 requestId 重放表：同一次写在换通道重投后不再执行第二遍。
-// 与 sendIdempotency 分开是因为键与生命周期不同（那边按 sessionId+clientMessageId，60s）。
+// 与 sendIdempotency 分开是因为键与生命周期不同（那边按 sessionId+clientMessageId，
+// 成功之后留到进程结束；这里是每次写各自的 requestId、只活在重投窗口里）。
 const writeIdempotency = new WeakMap();
 
 // 工作区列表的条件刷新短路：上次构建留下的 revision / 生成时刻 / 当时的信号代号。
@@ -265,6 +266,44 @@ function sendIdempotencyStateOf(ctx) {
   return state;
 }
 
+/**
+ * 同一个投递 id 在一次会话里只真正跑一次：成功之后记录留到进程结束，失败立刻释放。
+ *
+ * 要防的是「请求超时、但那一发其实已经交给宿主了」这一档：App 会拿着同一个
+ * clientMessageId 再发一次（内核重试或用户手点重试），第二次必须拿到第一次的结果，
+ * 而不是让模型 / 子代理把同一句话再说一遍。
+ *
+ * **失败不占位**：`run` 回的信封不是成功（宿主明确拒绝，如 model-unavailable /
+ * agent-busy）就当场删掉记录 —— 一次瞬时错误不能被固化成「这个 id 永远只回这一句错」；
+ * 同理 `run` 抛错（传输层失败）也删。两条都必须是「真的再试一次」，否则活的路径只剩
+ * 用户重开 App。
+ *
+ * @param {object} ctx 插件上下文（状态按 ctx 隔离）
+ * @param {string} key 投递身份：主会话 `sessionId:clientMessageId`，子代理额外加前缀
+ * @param {() => Promise<object>} run 真正发一次，回宿主信封（`{ result: { ok, value | error } }`）
+ */
+function promptOnceFor(ctx, key, run) {
+  const state = sendIdempotencyStateOf(ctx);
+  const existing = state.get(key);
+  if (existing) return existing.promise;
+
+  const promise = Promise.resolve().then(run);
+  const record = { promise };
+  state.set(key, record);
+  const release = () => { if (state.get(key) === record) state.delete(key); };
+  promise.then(
+    (response) => {
+      // 留下的这条记录就是「这一发已经交给宿主了」的回执；宿主明确拒绝（信封 ok 不为真）
+      // 就当场释放 —— 一次业务错误不能被固化成「这个 id 永远只回这一句」。这里只看收没
+      // 收下，不拆错误信封（拆信封在 envelope.js，本文件是零依赖的叶子）。
+      const accepted = Boolean(response && response.result && response.result.ok === true);
+      if (!accepted) release();
+    },
+    release,
+  );
+  return promise;
+}
+
 /** 写操作幂等表（实现在 mobile/idempotency.js，这里只保证按 ctx 隔离）。 */
 function writeIdempotencyStateOf(ctx) {
   let state = writeIdempotency.get(ctx);
@@ -356,5 +395,6 @@ module.exports = {
   workspaceShortcutStateOf,
   bumpCompletionGeneration,
   sendIdempotencyStateOf,
+  promptOnceFor,
   writeIdempotencyStateOf,
 };

package/lib/mobile/session-file.js

@@ -8,17 +8,24 @@
  *
  * 三条边界同时成立：
  *
- *  1. **只认本会话 present 声明过的路径**：`deliverables/presented` 是模型显式交出来的
- *     那份清单，App 卡片上的每一格都来自它。别把它放宽成「会话工作区里的任意文件」——
- *     移动 API 不暴露任意读，与它不暴露 shell / 任意写入是同一条边界。路径按**字符串
- *     全等**比对声明，所以不存在穿越。
- *  2. **相对路径按会话工作区解析**：声明里既可能是 `src/x.png` 也可能是绝对路径，
- *     相对的那一种只能相对 cwd 解析（cwd 取自会话列表摘要，与 /session 同一个来源）。
+ *  1. **放行面 = 本会话工作区里的文件 ∪ 本会话 present 声明过的路径**（2026-10-25 用户拍板
+ *     的第二条，见 docs/decisions.md）。前者的判法是「解析后的落点在 cwd 之下」：相对路径
+ *     按 cwd 拼、绝对路径原样，然后整条路径必须在 cwd 里 —— 所以 `../x` 这种穿越落在
+ *     cwd 之外，退回旧的那条白名单，不在声明里就 403。后者保持原样（`deliverables/presented`
+ *     里显式声明过的、**字符串全等**），它的用处是工作区之外的文件也能交付（绝对路径、
+ *     cwd 变了的老会话）。
+ *
+ *     **为什么敢放开工作区**：正文里模型写的 `[报告](docs/报告.md)` 就是这条路上的用户预期
+ *     —— 手机上点一下能看，比「点了没反应」有意义得多；而这条会话的模型本来就能读同一个
+ *     工作区，手机与电脑是同一个使用者，放宽的是「同一份工作区能不能在手机上看」，不是
+ *     「能不能读这台电脑上的任意文件」（那仍然是 403，与不暴露 shell / 任意写入同一条边界）。
+ *  2. **相对路径按会话工作区解析**：cwd 取自会话列表摘要（与 /session 同一个来源）。没有
+ *     cwd 的会话只能走 present 那条白名单，相对路径解析不出来就回 409。
  *  3. **流式回写、不在插件进程里缓冲**：几十 MB 的录屏不该整包躺在内存里，与会话日志
  *     导出同一个理由。
  *
- * 取不到时两种失败要分得开：不在声明里回 403（`not-presented`），声明里有、盘上没了
- * 回 404（`missing`）—— 前者是「这一格不该出现」，后者是「文件被挪走了」，文案不同。
+ * 取不到时两种失败要分得开：两条口子都不认这个路径就回 403（`outside-workspace`），
+ * 认了、盘上没了回 404（`missing`）—— 前者是「这个路径不该被读」，后者是「文件被挪走了」。
  */
 
 const fs = require('node:fs');
@@ -26,6 +33,7 @@ const { stat } = require('node:fs/promises');
 const path = require('node:path');
 const { pipeline } = require('node:stream/promises');
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { signedPath } = require('../shared/e2ee-request');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { presentedPathsOf } = require('./history-derive.js');
@@ -97,6 +105,19 @@ async function declaredPathsOf(ctx, sessionId) {
   return presentedPathsOf((value && value.events) || []);
 }
 
+/**
+ * 落点在不在工作区里。
+ *
+ * `path.relative` 出来是空的（就是 cwd 本身）或者以 `..` 开头（爬出去了）都算不在，
+ * 这样 `../x`、`a/../../x` 这些写法一并挡住 —— 判的是**解析后的真实落点**，不是输入字符串，
+ * 所以「看起来没写过 ..」最终指到外面的路径同样过不去。
+ */
+function isInsideWorkspace(cwd, target) {
+  if (!cwd) return false;
+  const rel = path.relative(path.resolve(cwd), target);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
 /** 会话的工作区目录（相对路径的解析基准）。取不到就回空串，由调用方决定怎么办。 */
 async function cwdOf(ctx, sessionId) {
   try {
@@ -124,34 +145,35 @@ async function handleSessionFile(ctx, req, res) {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, path }' } });
   }
 
-  let declaredPaths;
-  try {
-    declaredPaths = await declaredPathsOf(ctx, sessionId);
-  } catch (error) {
-    return sendJson(res, 502, {
-      ok: false,
-      error: { code: 'history-failed', message: String((error && error.message) || error) },
-    });
-  }
-  if (!declaredPaths.has(declared)) {
-    return sendJson(res, 403, {
-      ok: false,
-      error: { code: 'not-presented', message: '这个文件不在本会话的交付声明里' },
-    });
-  }
+  // 先把落点算出来：工作区那一侧判的是**解析后的真实路径**，不是输入字符串。
+  const cwd = await cwdOf(ctx, sessionId);
+  let target = path.isAbsolute(declared) ? path.resolve(declared) : '';
+  if (!target && cwd) target = path.resolve(cwd, declared);
 
-  let target;
-  if (path.isAbsolute(declared)) {
-    target = declared;
-  } else {
-    const cwd = await cwdOf(ctx, sessionId);
-    if (!cwd) {
+  // 工作区里的文件直接放行，一次历史都不读 —— 这是正文里点的链接走的那条路。
+  if (!target || !isInsideWorkspace(cwd, target)) {
+    // 工作区之外只剩交付声明这一条口子（绝对路径、或 cwd 变了的老会话）。
+    let declaredPaths;
+    try {
+      declaredPaths = await declaredPathsOf(ctx, sessionId);
+    } catch (error) {
+      return sendJson(res, 502, {
+        ok: false,
+        error: { code: 'history-failed', message: String((error && error.message) || error) },
+      });
+    }
+    if (!declaredPaths.has(declared)) {
+      return sendJson(res, 403, {
+        ok: false,
+        error: { code: 'outside-workspace', message: '这个路径不在本会话的工作区里，手机上打不开' },
+      });
+    }
+    if (!target) {
       return sendJson(res, 409, {
         ok: false,
         error: { code: 'no-cwd', message: '这条会话没有工作区目录，没法解析相对路径' },
       });
     }
-    target = path.join(cwd, declared);
   }
 
   let info;
@@ -221,14 +243,17 @@ async function handleSessionFile(ctx, req, res) {
  */
 async function writeEncryptedFile(req, res, target, opened) {
   const e2ee = require('../shared/e2ee');
-  const path0 = e2ee.signedPath(req);
   const requestNonce = opened.req.nonce;
   let seq = 0;
   let pending = Buffer.alloc(0);
   let closed = false;
   res.on('close', () => { closed = true; });
-  const stream = fs.createReadStream(target, { highWaterMark: FILE_CHUNK_BYTES });
+  // **整段都在 try 里**：调用点已经 `writeHead(200)` 过了，此后任何一步抛错都改不了状态码，
+  // 而 `sendJson` 再想写一个 500 只会撞上「头已发出」被静默吞掉 —— 响应就永远不结束，
+  // 手机上表现成「下载中」一直转、首字节等到超时。所以只能主动断开，让对端按截断处理。
   try {
+    const path0 = signedPath(req);
+    const stream = fs.createReadStream(target, { highWaterMark: FILE_CHUNK_BYTES });
     for await (const chunk of stream) {
       if (closed) break;
       pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;

package/lib/mobile/session-last-turn.js

@@ -14,6 +14,13 @@
  */
 
 const { lastTurnFactsOf } = require('./session-cache.js');
+const readReceipts = require('../read-receipt.cjs');
+
+/**
+ * 本进程的起点：只有它**之前**留下的已读水位才需要从盘上补回来（见 `lastTurnOf`）。
+ * 本进程内的读一律由 `recordSessionRead` 当场写进内存那张表，不必再查盘。
+ */
+const PROCESS_STARTED_AT = Date.now();
 
 /**
  * 一轮的结局：纯计算，不碰水位、不碰设备。
@@ -86,6 +93,9 @@ function recordSessionRead(ctx, sessionId, at = Date.now()) {
   const facts = lastTurnFactsOf(ctx);
   const previous = facts.get(sessionId) || {};
   const current = typeof previous.readAt === 'number' ? previous.readAt : 0;
+  // 同时落一份到盘上（lib/read-receipt.cjs）：内存这张表随进程消失，而 App 侧栏的绿点
+  // 靠的正是这里的水位 —— 桌面读过之后宿主一重启，同一轮又被算成未读（2026-10-26 真机）。
+  try { readReceipts.recordRead(sessionId, value); } catch { /* 台账是旁路 */ }
   if (current >= value) return false;
   facts.set(sessionId, { ...previous, readAt: value });
   return true;
@@ -96,11 +106,21 @@ function recordSessionRead(ctx, sessionId, at = Date.now()) {
  *
  * 只回带 `turn` 的那些：表里也可能只存着一个已读水位（读过、但插件重启后还没折过
  * 那一轮的结局），那不是「上一轮发生了什么」，不该下发给 App。
+ *
+ * 进程刚起来时那张表是空的，「桌面读过」只留在盘上那本台账里 —— 不补回来的话 App 会按
+ * 「没人读过」重算，早就读过的一轮又亮成绿点。只补上一次进程留下的那些（本进程里的读
+ * 已经在表里了），补到的值写回表里，让后面的折叠沿用。
  */
 function lastTurnOf(ctx, sessionId) {
-  const fact = lastTurnFactsOf(ctx).get(sessionId);
+  const facts = lastTurnFactsOf(ctx);
+  const fact = facts.get(sessionId);
   if (!fact || typeof fact.turn !== 'number') return undefined;
-  return fact;
+  const restored = readReceipts.readAtOf(sessionId);
+  const current = typeof fact.readAt === 'number' ? fact.readAt : 0;
+  if (!(restored > 0 && restored < PROCESS_STARTED_AT) || current >= restored) return fact;
+  const next = { ...fact, readAt: restored };
+  facts.set(sessionId, next);
+  return next;
 }
 
 module.exports = { settleOutcome, recordLastTurn, recordSessionRead, lastTurnOf };

package/lib/mobile/session-send.js

@@ -3,10 +3,11 @@
 /**
  * 发消息、slash 命令、会话的读/停/改名/分叉。
  *
- * promptOnce 的幂等窗口是这里唯一非平凡的逻辑：手机端发消息时网络重试与用户连点
- * 会产生同一个 clientMessageId 的多次请求，60 秒内它们共享同一个 prompt，而不是
- * 让模型跑两遍。**只缓存成功**：失败必须能被重试，不能把一次瞬时错误固化成 60 秒的
- * 静默无响应。
+ * promptOnce 的去重是这里唯一非平凡的逻辑：手机端发消息时网络重试与用户连点会产生
+ * 同一个 clientMessageId 的多次请求，同一会话内它们共享同一个 prompt，而不是让模型跑
+ * 两遍。成功之后记录一直留着（不按时间窗过期）：请求超时的那一发很可能已经交给宿主了，
+ * 用户隔几分钟再点一次重试，过期的窗口正好把同一条消息又发一遍。
+ * **只缓存成功**：失败必须能被重试，不能把一次瞬时错误固化成一条永远发不出去的消息。
  *
  * 文本块恰好一个且以 / 开头时派发为 slash 命令（commands.execute，不发给模型）；
  * 未知命令或网关未组合时回退普通消息，与桌面 miss 落入默认 sink 的行为一致。
@@ -18,12 +19,11 @@ const { unwrap } = require('./envelope.js');
 const { callSessions, mobilePromptRpcId } = require('./rpc.js');
 const {
   canonicalDeviceKey, invalidateSessionList, invalidateSessionModels,
-  markCompletionRead, sendIdempotencyStateOf,
+  markCompletionRead, promptOnceFor,
 } = require('./session-cache.js');
 const { promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
 const { withIdempotency, requestIdOf } = require('./idempotency.js');
 const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
-const readReceipt = require('../read-receipt.cjs');
 const { recordSessionRead } = require('./session-last-turn.js');
 
 /**
@@ -86,25 +86,9 @@ function promptOnce(ctx, clientMessageId, payload) {
   // 因为实时帧里的图还被漏读，张数一对不上就彻底认领不了）。
   const request = clientMessageId ? { ...payload, requestId: rpcId } : payload;
   if (!clientMessageId) return callSessions(ctx, 'prompt', request, rpcId);
-  const state = sendIdempotencyStateOf(ctx);
-  const key = `${payload.sessionId}:${clientMessageId}`;
-  const now = Date.now();
-  const existing = state.get(key);
-  if (existing && now - existing.createdAt < 60_000) return existing.promise;
-  if (existing) state.delete(key);
-
-  const promise = Promise.resolve(callSessions(ctx, 'prompt', request, rpcId));
-  // Keep the short-lived record so an in-flight/concurrent send with the same
-  // clientMessageId shares one prompt. Only cache a SUCCESS: a rejection must
-  // not poison later retries (a transient error should be retryable), so the
-  // record is released on failure.
-  const record = { createdAt: now, promise };
-  state.set(key, record);
-  promise.then(
-    () => { /* resolved stays cached until the 60s window expires */ },
-    () => { if (state.get(key) === record) state.delete(key); },
-  );
-  return promise;
+  // 同一个 clientMessageId 在本会话里只承诺一次：内核重试、以及隔了几分钟用户手点的
+  // 那次，都拿同一份结果（口径见 session-cache 的 `promptOnceFor`）。
+  return promptOnceFor(ctx, `${payload.sessionId}:${clientMessageId}`, () => callSessions(ctx, 'prompt', request, rpcId));
 }
 
 async function handleSend(ctx, req, res) {
@@ -230,17 +214,11 @@ async function handleSessionRead(ctx, req, res, fallbackDeviceKey = 'legacy') {
   markCompletionRead(ctx, deviceKey, body.sessionId);
   // 「这一轮被读过了」还要记一笔**设备无关**的水位：列表要喂镜像快照（全局一份），
   // 上面那份按设备的提醒进不了下行清单，App 那边根本看不到这次已读（见 session-last-turn.js）。
+  // 这一笔同时会落进盘上的已读台账（桌面端绿点靠它），所以这里不再单独写一遍。
   recordSessionRead(ctx, body.sessionId);
   // Invalidate the cache and any build already reading history. Its generation
   // check prevents a stale build from restoring `completed` after this ack.
   invalidateSessionList(ctx, deviceKey);
-  // 桌面端的未读绿点不在宿主里（它在浏览器渲染进程的内存里），这里只记一条水位，
-  // 由插件的客户端半边拉走、在桌面页面里就地清掉。写盘失败不该让「已读」这个动作失败。
-  try {
-    readReceipt.recordRead(body.sessionId);
-  } catch {
-    // 回执台账只是尽力而为的旁路，读不到/写不动都不影响本次已读本身。
-  }
   sendJson(res, 200, { ok: true, accepted: true });
 }
 

package/lib/mobile/session-snapshot.js

@@ -171,12 +171,11 @@ async function handleMessages(ctx, req, res) {
   const messages = deriveMessages(resolvedEvents);
   const hasMore = !!(value && value.hasMore);
   const items = wantThin ? thinEntryMessages(messages, { hasMore }) : messages;
-  // 工具结果不产生消息行，但会把**缓存里已有的**工具卡从 running 补成最终态。补丁必须
-  // 取自整个窗口（不只是 seq > afterSeq 的那一段）：调用方游标可能已经越过结果 seq，
-  // 而工具卡还停在 running；客户端按 callId 幂等打补丁。已经随消息块下发的那些只回状态，
-  // 不重复带正文（规则与理由见 history-derive 的 toolResultPatchesFor）。
-  // 入口裁剪那一发不带补丁：过程块已摘掉、补丁无处可打，跟着走等于把工具输出又塞回顶层。
-  const toolResults = wantThin ? [] : toolResultPatchesFor(events, items);
+  // 工具结果不产生消息行，但会把**缓存里已有的**工具卡从 running 补成最终态。补丁取自
+  // 整个窗口（调用方游标可能已越过结果 seq）；已随消息块下发的只回状态（见 toolResultPatchesFor）。
+  // 增量那一发（带 afterSeq）一律只回状态：调用方手上已有一份会话，整窗重发等于每 15 秒
+  // 把最近两百条的工具输出再传一次；入口裁剪那一发不带补丁（过程块已摘掉、无处可打）。
+  const toolResults = wantThin ? [] : toolResultPatchesFor(events, items, { bodies: afterSeq === null });
   const seqs = events.map(eventSeqOf).filter((seq) => Number.isSafeInteger(seq) && seq >= 0);
   const oldestSeq = seqs.length ? Math.min(...seqs) : null;
   // A truncated history window is not a complete incremental answer. Keep the