dsh-mobile-plugin 0.4.0 → 0.4.4

package/lib/mobile/envelope.js

@@ -3,22 +3,11 @@
 /**
  * 宿主 apiProxy 的回执信封。
  *
- * 宿主所有 `apiProxy.*` 调用都回同一个形状：
- *   成功 `{ result: { ok: true,  value } }`
- *   失败 `{ result: { ok: false, error: { code, message, details? } } }`
- *   异常（只有 envelope.js 之外的调用方会碰到）`{ result: { ok: true, value } }` 的缺位形态
+ * 所有 `apiProxy.*` 调用都回同一个形状：成功 `{ result: { ok: true, value } }`，失败
+ * `{ result: { ok: false, error: { code, message, details? } } }`。
  *
- * 以前这个拆信封的动作在仓库里有 6 种写法：history-derive.js / workspaces.js /
- * agent-presets.js 三份逐字相同；session-cleanup.cjs 是「只取 value」的变体；
- * plugins.js / references.js 在此之上又叠了各自的字段校验与错误码
- * （那两个是有意的领域解码，不算重复）；auto-archive.cjs 则干脆绕过信封直接读
- * `response?.value?.items`——它读的那一层压根不是信封，是 bug。
- *
- * 把唯一实现收到这里，是因为 5 个模块为了拿这 5 行去 require 一个 1400 行、
- * 带 9 个模块级 WeakMap 的 sessions.js——那才是 sessions.js 拆不动的真正原因：
- * 它同时扮演了会话领域、缓存中心、RPC 封装和公共工具库四个角色。
- *
- * 依赖方向：envelope.js 是叶子模块，不 require 任何东西。
+ * 拆信封只有这一份实现：此前几个模块各写一遍，还要为了这 5 行去 require 一个 1400 行的
+ * sessions.js。envelope.js 是叶子模块，不 require 任何东西。
  */
 
 /**

package/lib/mobile/events.js

@@ -1,20 +1,13 @@
 /**
  * 设备级事件流（GET /api/mobile/v1/events/stream）：手机上侧栏那条 SSE。
  *
- * 它只被当成「有东西变了」的信号，绝不当作数据源（真正的数据还要 App 自己去拉列表），
- * 所以这里把每条宿主帧削到只剩能表示「列表需要重拉」的部分（见 listRelevantPayload）。
- * 但宿主在 DSH 0.2.0 兼容桥下只会订阅 workspace/follow + session/control，会话状态变化
- * 走的是 session/projection（被白名单丢掉），于是这条流连着却可能长时间一帧都不发；
- * 插件自己补了 device/list-changed（来自 lib/shared/list-signal.js，清单变了）、
- * device/session-activity（来自 lib/shared/session-signal.js，某个会话的正文水位涨了）、
- * device/desktop-view-changed（来自 lib/shared/desktop-view-signal.js，桌面侧栏折叠态
- * 变了）与 device/heartbeat（心跳）四类自产帧，App 侧靠它们判断「这条流还活着」
- * 「该重拉列表」「该给某个会话补正文」「该重取折叠态」并据此决定要不要把兜底轮询降频。
+ * 它只是「有东西变了」的信号，绝不是数据源，所以每条宿主帧都削到只剩「列表需要重拉」的
+ * 部分。0.2.0 兼容桥只订阅 workspace/follow + session/control，会话状态变化会被丢掉；插件
+ * 因此自产四类帧：device/list-changed、device/session-activity、device/desktop-view-changed
+ * 与 device/heartbeat，App 靠它们判断流还活着并决定是否降频兜底轮询。
  *
- * 断流补偿：这条流不做 Last-Event-ID 续传（App 只把它当信号，不当数据源），所以**连上时**
- * 会立刻补发「当前状态」——一帧最近已知 revision 的 device/list-changed + 每个已跟踪会话
- * 各一帧 device/session-activity（见 replayKnownSignals）。补的是断流窗口，不是新变更：
- * 只读信号总线的快照，不 bump、不前移基准，App 侧对同 revision / 同水位幂等。
+ * 这条流没有 Last-Event-ID 续传，所以连上时立刻补一帧当前 revision 与每个已跟踪会话的水位；
+ * 补的是断流窗口，不是新变更。
  */
 'use strict';
 
@@ -30,11 +23,8 @@ const DEDUP_WINDOW = 2048;
 const HEARTBEAT_MS = 15_000;
 
 /**
- * 诊断日志。这条流过去的失败路径是一个空 catch（里面只有一句「客户端断开或流已结束」
- * 的注释），于是「连着却一句话都不说」在宿主侧没有任何痕迹：手机把兜底轮询降成 60s，
- * 而宿主日志里查不到这条流是正常收尾、被客户端断开，还是循环抛错。会话级流
- * （mobile/stream.js）早就有 logStream，这里是它的设备级对偶——任何一条异常路径都必须
- * 留下可 grep 的行。
+ * 诊断日志。失败路径一条都不许静默：手机把兜底轮询降成 60s，宿主日志里却查不到这条流是
+ * 正常收尾、被客户端断开，还是循环抛错。会话级流早有 logStream，这里是它的设备级对偶。
  */
 function logDeviceStream(message, error) {
   const detail = error instanceof Error ? (error.stack || error.message) : (error == null ? '' : String(error));
@@ -46,11 +36,9 @@ function logDeviceStream(message, error) {
 /**
  * 写一条 SSE 记录（策略声明，实现见 `lib/shared/sse-write.js`）。
  *
- * 这条流的策略：软水位**一律** shed —— 但 shed 不能当成功：设备流没有 Last-Event-ID
- * 续传，丢了帧又继续读，App 就会停在缺少那一次变更的状态。所以调用方看到 `shed` 必须
- * 立即 `abort` 断流，让客户端重连后走 `replayKnownSignals()` 全量补水位。
- * 这比把帧堆在写缓冲里好（2026-10-17 现场：466MB 的 SSE 帧挂在 socket 写队列上，宿主撞
- * 4GB 上限被杀）。不补填充：这里的帧少、单帧也小，不需要撑 RN 的缓冲阈值。
+ * 这条流的软水位一律 shed，而 shed 不能当成功：没有 Last-Event-ID 续传，丢了帧又继续读，
+ * App 就会停在缺少那一次变更的状态。所以调用方看到 `shed` 必须立即断流，让客户端重连后
+ * 走 `replayKnownSignals()` 全量补水位 —— 这比把帧堆在写缓冲里好。
  *
  * 返回值与会话流一致：`ok:false` 该收尾，`shed:true` 这条被丢掉（调用方必须断流），
  * `needDrain:true` 写进去了但底下已经写不动。
@@ -60,7 +48,7 @@ function writeSse(res, payload, frame, sealFrame) {
     frame,
     namespace: 'device',
     // 协议 v2 的会话上这条流也逐帧封装：`App` 判定「这条会话是加密的」之后，收到一帧
-    // 明文就当畸形帧计数，连着十帧就把整条流判死、退回 15 秒轮询（2026-10-24 现场）。
+    // 明文就当畸形帧计数，连着十帧就把整条流判死、退回 15 秒轮询。
     sealFrame: typeof sealFrame === 'function' ? sealFrame : null,
     shedWhenBuffered: () => true,
   });
@@ -87,14 +75,10 @@ async function* mergeHostAndMux(ctx, signal) {
 }
 
 /**
- * Trim a device-wide stream payload to the metadata the mobile session-list
- * actually consumes. `session/event` frames carry the FULL message content
- * (payload.event.data includes the whole assistant/user message); forwarding
- * them to every paired phone floods the relay and the client with megabytes
- * whenever a session is actively generating. The device-wide stream is only
- * used by the phone to refresh the session list (turn/start/end/title), so it
- * needs the event identity and inner type, not the content. Other frame types
- * (summary/queue/projection/question/approval/host) are small and kept intact.
+ * Trim a device-wide stream payload to the metadata the mobile session-list consumes.
+ * `session/event` frames carry the full message content; forwarding them to every paired
+ * phone floods the relay whenever a session is generating. Only the event identity and
+ * inner type are needed. Other frame types are small and kept intact.
  */
 function lightPayload(payload) {
   if (!payload || typeof payload !== 'object' || payload.type !== 'session/event') return payload;
@@ -174,15 +158,13 @@ async function handleDeviceStream(ctx, req, res) {
     return !result.needDrain;
   };
   /**
-   * 自产的「清单变了」帧：镜像推送调度器每 500ms 比一次清单内容哈希，变了就在这里推给手机。
+   * 自产的「清单变了」帧：镜像推送调度器每 500ms 比一次清单内容哈希，变了就推给手机。
    *
-   * 设备级流此前只有宿主事件这一个来源，而宿主的 0.2.0 兼容桥只订阅 workspace/follow +
-   * session/control，会话状态变化（session/projection）会被 listRelevantPayload 丢掉 ——
-   * 手机于是「连着却收不到任何会话状态变化」，兜底轮询又被降成 60s。这里补上真源。
+   * 设备级流此前只有宿主事件这一个来源，而 0.2.0 兼容桥的订阅里没有 session/projection，
+   * 会话状态变化会被丢掉，手机于是「连着却收不到任何变化」。
    *
-   * 走直订而不是塞进 mergeHostAndMux：那是个无限流，混进去之后「宿主事件流结束」就不再
-   * 等于「这条 SSE 该收尾」。watch() 让推送调度器知道有人在听（隧道断着也照常判定），
-   * 收尾时必须注销，否则它永远以为有人听。
+   * 走直订而不是塞进 mergeHostAndMux：那是个无限流，混进去之后「宿主事件流结束」就不再等于
+   * 「这条 SSE 该收尾」。watch() 让推送调度器知道有人在听，收尾时必须注销。
    */
   const releaseSignal = sharedListSignal.watch();
   const unsubscribeSignal = sharedListSignal.onBump((event) => {
@@ -192,17 +174,12 @@ async function handleDeviceStream(ctx, req, res) {
   /**
    * 自产的「某个会话的正文水位涨了」帧，与「清单变了」是两条独立的通知。
    *
-   * 清单信号只说「列表内容变了」，手机据此重拉列表；但列表摘要里的 lastMessage 只是
-   * 一句话，正文（回复的长文本、提问的选项）在会话缓存里。没有这条帧时，只有**打开着**
-   * 那个会话的手机才会实时收到正文（session/stream 是按会话订阅的），没打开的会话要等
-   * 用户点进去才拉 —— 而这正好是「点开对话要等一会儿才看到内容」的来源。
+   * 清单信号只说列表内容变了；而正文在会话缓存里，没有这条帧时只有打开着那个会话的手机才
+   * 会实时收到正文，没打开的会话要等点进去才拉 —— 这正是「点开对话要等一会儿才看到内容」
+   * 的来源。
    *
-   * 水位由镜像调度器**算出后广播**，与镜像是否真的推进去解耦（见 lib/mirror/pusher.cjs
-   * 的 announceSessionActivity：隧道未连、内容未变跳过、推送成功三条路径都会广播）——
-   * 它说的是「本机正文到哪了」，不是「中转镜像里有到哪了」。手机收到帧后立刻带 afterSeq
-   * 去 /session/messages 增量拉：走中转的手机读到的是刚推上去的镜像，走局域网直连的手机
-   * 读到的是 sidecar 本地那份快照（/tunnel/send 先落盘再尝试发），两条路都拿得到。
-   * 同样必须直订 + 收尾注销，理由与上面那条一致。
+   * 水位由镜像调度器算出后广播，说的是「本机正文到哪了」，不是「中转镜像里有到哪了」，与
+   * 镜像是否真的推成功解耦。同样必须直订 + 收尾注销。
    */
   const unsubscribeActivity = sharedSessionSignal.onBump((event) => {
     if (ac.signal.aborted) return;
@@ -211,14 +188,12 @@ async function handleDeviceStream(ctx, req, res) {
   /**
    * 自产的「桌面侧栏折叠态变了」帧。
    *
-   * 桌面端那份 groupExpansion 只活在浏览器 localStorage，插件靠客户端半边轮询上报，
-   * 落在 lib/desktop-view.cjs；手机要拿到它只能问 GET /desktop-view。过去 App 用
-   * 「跟列表刷新走 + 5 分钟最短间隔」去猜它有没有变，稳态下一天白问几百次 —— 而插件
-   * 早就知道它哪一刻变了（desktop-view.cjs 的 update()）。这里补上那个出口。
+   * groupExpansion 只活在浏览器 localStorage，插件靠客户端半边轮询上报落在
+   * lib/desktop-view.cjs；手机要拿它只能问 GET /desktop-view。过去 App 按「跟列表刷新走 +
+   * 5 分钟最短间隔」去猜它变没变，而插件早就知道它哪一刻变了。
    *
-   * 只发 updatedAt、不发内容：手机据此重拉那一发，拿到的是与列表同一口径的完整镜像，
-   * 也不必让这条「信号流」承担数据同步（它的帧一律可丢、可重放）。
-   * 同样必须直订 + 收尾注销，理由与上面两条一致。
+   * 只发 updatedAt、不发内容：手机据此重拉那一发，不必让信号流承担数据同步。
+   * 同样必须直订 + 收尾注销。
    */
   const unsubscribeDesktopView = sharedDesktopViewSignal.onBump((event) => {
     if (ac.signal.aborted) return;
@@ -227,16 +202,11 @@ async function handleDeviceStream(ctx, req, res) {
   /**
    * 连上就先补一帧「当前状态」。
    *
-   * 设备级流没有会话级流那套 Last-Event-ID 续传（App 对这条流不做断点续传，它只把帧
-   * 当「有东西变了」的信号），所以断流窗口里发生的清单变更与正文水位在重连后必须补上。
-   * 不补的后果：手机重连后 state 是空的，而侧栏兜底轮询已经因为「流活着」被降到 60s ——
-   * 中间这几分钟的变化要等到下一次真实变更才可见。
+   * 这条流没有 Last-Event-ID 续传，断流窗口里发生的清单变更与正文水位必须在重连后补上，
+   * 否则手机 state 是空的，而兜底轮询已经因为「流活着」被降到 60s。
    *
-   * 这里只读两条信号总线**已经广播过**的最近值（snapshot），既不 bump 也不前移任何基准，
-   * 所以不会制造新变更、不影响推送侧的幂等。App 侧对同 revision / 同水位是幂等的
-   * （app 的 handleDeviceSignal 按 revision 与 seq 判重），重连补发不会引发重复刷新。
-   * 帧形状与实时帧完全一致（同为 device/event 信封包 device/list-changed 或
-   * device/session-activity），App 不需要任何改动。
+   * 只读两条信号总线已经广播过的最近值，既不 bump 也不前移基准，所以不会制造新变更；
+   * App 对同 revision / 同水位幂等，重连补发不会引发重复刷新。
    */
   const replayKnownSignals = () => {
     const list = sharedListSignal.snapshot();

package/lib/mobile/extensions.js

@@ -3,15 +3,12 @@
 /**
  * 扩展卡的宿主侧：卡状态账本、扩展动作登记表，以及给模型用的 `extension_present` 工具。
  *
- * 为什么卡状态要落在宿主家里：一张卡「现在长什么样」不能只靠声明它的那一次工具调用。
- * 扩展页回写标题与说明之后，手机上重进会话、刷新列表都会从历史重新拼卡 —— 没有这份账本，
- * 卡会一直停在声明那一刻的样子（卡的状态得由宿主认账）。账本与会话
- * 日志无关，清理会话不连带它，与统计账本同口径。
+ * 卡状态要落在宿主家里：扩展页回写标题与说明之后，手机重进会话、刷新列表都会从历史重新
+ * 拼卡，没有这份账本，卡就停在声明那一刻的样子。账本与会话日志无关，清理会话不连带它。
  *
- * 为什么动作名是一张硬编码白名单：扩展是网页，它能让宿主做的事必须由宿主预先枚举，而不是
- * 由扩展在消息里现拼一个动作名交给宿主执行。这条边界和移动 API 的能力面是同一条 —— 移动
- * API 不暴露 shell、系统设置、任意文件读写，这里也一个都不开。**登记表现在是空的**：宿主动作
- * 这一档还没有对任何扩展放开，所以任何动作名都必须被拒。
+ * 动作名是一张硬编码白名单：扩展能让宿主做的事必须由宿主预先枚举，不能在消息里现拼一个
+ * 动作名。这条边界与移动 API 的能力面相同——不暴露 shell、系统设置、任意文件读写。
+ * 登记表现在是空的，所以任何动作名都必须被拒。
  */
 
 const fs = require('node:fs');

package/lib/mobile/file-read.js

@@ -0,0 +1,168 @@
+'use strict';
+
+/**
+ * 按路径读文件（POST /api/mobile/v1/file/read）：右栏文件浏览器「点开一个文件」。
+ *
+ * 与 `/session/file` 的分工：那条服务的是**交付**（卡片、正文里的文件链接），放行面是
+ * 「本会话工作区 ∪ 本轮 present 声明过的路径」；右栏能一路翻到别的已登记工作区，手里的
+ * 就是一串路径，所以这条按 `allowed-zone.js` 判：宿主已登记的工作区 ∪ 当前会话的项目目录。
+ *
+ * 三条边界：
+ * 1. `path` 必须是绝对路径 —— 这条路由没有可信的解析基准，相对路径直接 400，不去猜谁当基准。
+ *    判定用的是 resolve 之后的落点，`..` 爬出允许区一律不认（403 `outside-allowed`）。
+ * 2. 认出允许区之后的失败分开报：盘上没有 404 `missing`、不是普通文件 400 `not-a-file`、
+ *    超过 512MB 413 `too-large`。码与文案跟 `/session/file` 同一套，App 那边一套分支就够。
+ * 3. 字节流式回写，不在插件进程里缓冲。协议 v2 的分块信封**直接调 `/session/file` 那个写入
+ *    函数**：两边抄一份形状必然漂，而漂了的症状是「手机上永远下载中」，没有报错。
+ */
+
+const fs = require('node:fs');
+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 { allowedRoots, inAllowedZone } = require('./allowed-zone.js');
+const { writeEncryptedFile, SESSION_FILE_MAX_BYTES } = require('./session-file.js');
+
+/**
+ * 扩展名 → 内容类型。与 `session-file.js` 那张表逐条相同：两条路给同一个文件必须给出同一个
+ * `content-type`，否则 App 那边「按类型决定怎么预览」的分支会看端点选，等于多一种行为。
+ */
+const MEDIA_TYPES = Object.freeze({
+  mp4: 'video/mp4', m4v: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm',
+  mp3: 'audio/mpeg', m4a: 'audio/mp4', wav: 'audio/wav', ogg: 'audio/ogg', flac: 'audio/flac',
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', heic: 'image/heic', bmp: 'image/bmp', svg: 'image/svg+xml',
+  pdf: 'application/pdf',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  zip: 'application/zip', gz: 'application/gzip', tar: 'application/x-tar',
+  json: 'application/json', csv: 'text/csv', html: 'text/html', htm: 'text/html',
+});
+
+const TEXT_EXTENSIONS = new Set([
+  'txt', 'md', 'markdown', 'log', 'json', 'csv', 'tsv', 'html', 'htm', 'css',
+  'js', 'jsx', 'ts', 'tsx', 'mjs', 'cjs', 'py', 'rb', 'go', 'rs', 'java', 'kt',
+  'swift', 'c', 'h', 'cpp', 'sh', 'bash', 'zsh', 'yml', 'yaml', 'toml', 'ini',
+  'conf', 'sql', 'xml', 'svg', 'patch', 'diff',
+]);
+
+/** 取扩展名（小写、不含点）；没有扩展名回空串。 */
+function extensionOf(filePath) {
+  const dot = filePath.lastIndexOf('.');
+  if (dot <= 0 || dot === filePath.length - 1) return '';
+  return filePath.slice(dot + 1).toLowerCase();
+}
+
+/** 回给响应的内容类型：认得出的按表，认不出的按扩展名落文本或 octet-stream。 */
+function mediaTypeOf(filePath) {
+  const ext = extensionOf(filePath);
+  if (MEDIA_TYPES[ext]) return MEDIA_TYPES[ext];
+  if (TEXT_EXTENSIONS.has(ext)) return 'text/plain; charset=utf-8';
+  return 'application/octet-stream';
+}
+
+/**
+ * `content-disposition` 的文件名：头里只能放 ASCII，中文名按 RFC 5987 另给一份
+ * `filename*`。App 不读它（文件名它自己有），留着是给别人抓包时认人用的。
+ */
+function dispositionOf(name) {
+  const ascii = name.replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+
+/**
+ * POST { path（绝对）, sessionId? } → 该文件的原始字节。
+ *
+ * @param {object} ctx 插件上下文
+ * @param {object} req node:http IncomingMessage
+ * @param {object} res node:http ServerResponse
+ */
+async function handleFileRead(ctx, req, res) {
+  const body = await readJsonBody(req);
+  const declared = body && typeof body.path === 'string' ? body.path.trim() : '';
+  const sessionId = body && typeof body.sessionId === 'string' ? body.sessionId.trim() : '';
+  if (!declared) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { path }（绝对路径）' } });
+  }
+  if (!path.isAbsolute(declared)) {
+    return sendJson(res, 400, {
+      ok: false,
+      error: { code: 'bad-request', message: 'path 必须是绝对路径' },
+    });
+  }
+  const target = path.resolve(declared);
+
+  let roots;
+  try {
+    roots = await allowedRoots(ctx, sessionId);
+  } catch (error) {
+    // 宿主那句原话回给手机：这条路上「没取到」与「你没有这个目录」必须分得开。
+    return sendJson(res, 502, {
+      ok: false,
+      error: {
+        code: (error && error.code) || 'workspace-list-failed',
+        message: String((error && error.message) || error),
+      },
+    });
+  }
+  if (!inAllowedZone(roots, target)) {
+    return sendJson(res, 403, {
+      ok: false,
+      error: { code: 'outside-allowed', message: '这个文件不在能看的范围里（只放行工作区目录和这条会话的项目目录）' },
+    });
+  }
+
+  let info;
+  try {
+    info = await stat(target);
+  } catch {
+    return sendJson(res, 404, { ok: false, error: { code: 'missing', message: '文件已经不在这台电脑上了' } });
+  }
+  if (!info.isFile()) {
+    return sendJson(res, 400, { ok: false, error: { code: 'not-a-file', message: '这条路径不是一个文件' } });
+  }
+  if (info.size > SESSION_FILE_MAX_BYTES) {
+    return sendJson(res, 413, {
+      ok: false,
+      error: { code: 'too-large', message: '这个文件太大，手机这边不支持整份取回' },
+    });
+  }
+
+  const header = {
+    'content-type': mediaTypeOf(target),
+    'content-disposition': dispositionOf(path.basename(target)),
+    'cache-control': 'no-store',
+  };
+
+  // 协议 v2：与 `/session/file` 逐字节同形（`x-dsh-content-type` 带明文类型、chunked，
+  // 真实类型单独给一份让 App 解密后决定怎么预览）。
+  const opened = req && req.__dshE2ee;
+  if (opened && opened.keys && opened.req) {
+    res.writeHead(200, {
+      ...header,
+      'content-type': 'application/x-dsh-e2ee-chunks',
+      'transfer-encoding': 'chunked',
+      'x-dsh-proto': '2',
+      'x-dsh-content-type': header['content-type'],
+    });
+    await writeEncryptedFile(req, res, target, opened);
+    return;
+  }
+
+  res.writeHead(200, { ...header, 'content-length': String(info.size) });
+  if (info.size === 0) return res.end();
+
+  const stream = fs.createReadStream(target);
+  res.on('close', () => stream.destroy());
+  try {
+    await pipeline(stream, res);
+  } catch {
+    // 头已经发出去了，改不了状态码，只能断开让对端按截断处理。
+    try { res.destroy(); } catch { /* 连接已关闭 */ }
+  }
+}
+
+module.exports = { handleFileRead, mediaTypeOf };

package/lib/mobile/git-repos.js

@@ -3,23 +3,14 @@
 /**
  * 项目目录的 Git 仓库识别：回传「这里有没有仓库、仓库根在哪、当前在哪个分支」。
  *
- * 为什么由插件做：手机看不到电脑上的目录，侧栏那个 Git 入口的可见性只能靠宿主回传的
- * 标记决定（docs/git-manager.md 第 2 节）。判据不许 App 猜，也不许等用户点进去才发现
- * 是空页 —— 字段缺失一律按「不是仓库」处理。
+ * 手机看不到电脑上的目录，侧栏 Git 入口的可见性只能靠宿主回传的标记；判据不许 App 猜，
+ * 字段缺失一律按「不是仓库」处理。
  *
- * 为什么只读文件、不起 git 进程：这段代码跟着工作区清单一轮一轮地跑（镜像推送每
- * 500ms 构建一次清单），起进程太贵；而且宿主上未必装了 git，装没装不该影响「这个项目
- * 是不是仓库」这个事实。仓库的形状就是 `.git` 这个入口加上里面的 HEAD，读到就够答了。
+ * 只读文件、不起 git 进程：这段代码跟着工作区清单一轮轮跑，起进程太贵，而且宿主未必装了
+ * git。三种都算有仓库：项目根自己就是仓库、项目落在某个仓库的子目录里（往上找最近的根）、
+ * 项目下面并列着若干仓库。往上走到主目录为止，往下只扫两层、条数封顶。
  *
- * 认哪些（三种都算「有仓库」）：
- *   1. 项目根自己就是仓库根；
- *   2. 项目目录落在某个仓库的子目录里 —— 往上找最近的那个根，操作按它执行；
- *   3. 项目下面并列着若干个仓库（第 1、2 层，含 `.git` 是文件的子模块与 worktree）。
- * 往上走到主目录为止不再往上：主目录本身是个 dotfiles 仓库时，再往上是把每个项目都
- * 判成仓库，那不是这些项目的意思。往下只扫两层、条数封顶，扫满置 `truncated`。
- *
- * 结果按目录缓存一会儿（GIT_CACHE_MS）：下拉刷新带 `fresh` 跳过缓存，见
- * lib/mobile/workspaces.js 的 handleWorkspaces。
+ * 结果按目录缓存一会儿，下拉刷新带 `fresh` 跳过。
  */
 
 const { readdir, readFile, stat } = require('node:fs/promises');

package/lib/mobile/git.js

@@ -1,26 +1,18 @@
 'use strict';
 
 /**
- * 移动端 Git 管理器：十一条 `/api/mobile/v1/git/*` 的 handler。
+ * 移动端 Git 管理器：`/api/mobile/v1/git/*` 的 handler。
  *
- * 能力面刻意收成**固定命名的动词**，不接受「传一条 git 命令」：这条 API 的边界是不暴露
- * shell，而 `git -c core.pager=less ...` 这种透传等于把 shell 交出去。所以这里只认
- * 「仓库摘要 / 变更清单 / 单个文件的 diff / 历史 / 单次提交 / 分支 / 概览」加上
- * 「暂存 / 取消暂存 / 提交 / 切分支 / 新建分支 / 推送到上游」这些动作，参数只有仓库、
- * 相对路径、分支名、提交信息四类值（push 连分支名都不收：只推当前分支到它自己的上游）。
+ * 能力面刻意收成固定命名的动词，不接受「传一条 git 命令」：这条 API 的边界是不暴露 shell，
+ * 透传等于把 shell 交出去。参数只有仓库、相对路径、分支名、提交信息四类值。
  *
- * 归属校验在这一层做两遍：① `workspaceId` 必须是这台设备已注册的工作区（宿主 `workspace.list`
- * 里找得到）；② 请求里的仓库根必须是 `lib/mobile/git-repos.js` 给这个项目识别出来的那几个根
- * 之一 —— 于是「随便传一个路径」这条路根本走不通，`..`、绝对路径、仓库外的目录都进不来。
+ * 归属校验做两遍：workspaceId 必须是本设备已注册的工作区；仓库根必须是 git-repos.js 给这个
+ * 项目识别出来的根之一，于是随意传路径、`..`、仓库外目录都进不来。写操作按仓库串行，避免
+ * 并发写撞 `.git/index.lock`，写完顺手回一份新的变更清单。
  *
- * 写操作按仓库串行（`withRepoLock`）：手机上连点两下就是两个并发写，撞上 `.git/index.lock`
- * 会互相踩死；写完顺手回一份新的变更清单，省掉前端一次往返。
- *
- * 明确不做：合并 / 变基 / 拣选 / 冲突解决 / 强制推送 / 删除远端分支 / 改配置与凭据 /
- * 子模块管理 / fetch、pull。**push 只做最窄的一档**（2026-10-22）：推当前分支到它已有的上游，
- * 不接受 `--force`、不收分支名参数 —— 远端分叉、没有上游一律拒掉并叫用户回电脑处理，
- * 因为「拉下来再合」这件事本来就留在电脑上。丢弃改动也没做 —— 那是不可恢复的删工作，
- * 接口留白比给一个能被误按的按钮安全。
+ * 明确不做合并 / 变基 / 拣选 / 冲突解决 / 强制推送 / 删除远端分支 / 改配置与凭据 / 子模块 /
+ * fetch、pull；push 只推当前分支到已有上游，远端分叉或没有上游一律拒掉。丢弃改动也没做，
+ * 接口留白比一个能被误按的按钮安全。
  */
 
 const { isAbsolute, resolve } = require('node:path');
@@ -434,8 +426,8 @@ function cleanCommitMessage(raw) {
  * `llm` 服务（跟渠道包、agent loop 同一条流式路径），让它写一行 Conventional Commits 标题填进
  * 提交框 —— 只是**填框**，不提交、不推送。跟 VSCode 那颗一致：没暂存也要能写。
  *
- * 边界：模型要由手机指定（选哪个是用户的事，宿主不猜）；工作区干净就直接拒（没有改动可总结，让模型凭空写一条比报错更糟）。（没有改动可总结，
- * 让模型凭空写一条比报错更糟）。这里只读 `git diff --cached`，不写盘。
+ * 边界：模型由手机指定（选哪个是用户的事，宿主不猜）；工作区干净就直接拒，让模型凭空写一条
+ * 比报错更糟。这里只读 diff，不写盘。
  */
 async function handleGitCommitMessage(ctx, req, res) {
   const body = await bodyJson(req);