dsh-mobile-plugin 0.1.95 → 0.1.97

package/README.md

@@ -1,81 +1,104 @@
-# dsh-mobile-plugin
+<h3 align="center">AI-HUB 移动端插件</h3>
 
-[English](EN-README.md)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/banner.png" alt="AI-HUB：用手机接着电脑上的 DSH 往下用" width="100%">
+</p>
 
-AI-HUB 手机端插件，为 DSH 提供移动 API、远程连接和局域网代理。插件也可作为无头 Cordis Host 独立运行，不依赖桌面外壳或 Electron。
+<p align="center">
+  <a href="https://apps.apple.com/us/app/ai-hub/id6821681438"><img alt="App Store" src="https://img.shields.io/badge/App_Store-%E4%B8%8B%E8%BD%BD-black?style=for-the-badge&logo=appstore&logoColor=white"></a>
+  <a href="https://app.wnluo.com/public/apps/14"><img alt="Android APK" src="https://img.shields.io/badge/Android_APK-%E4%B8%8B%E8%BD%BD-3DDC84?style=for-the-badge&logo=android&logoColor=white"></a>
+  <a href="https://github.com/WNLUO/dsh-mobile-plugin/releases/latest/download/ai-hub-android.apk"><img alt="GitHub APK" src="https://img.shields.io/badge/GitHub_APK-%E6%9C%80%E6%96%B0%E7%89%88-181717?style=for-the-badge&logo=github"></a>
+  <a href="https://testflight.apple.com/join/4fn5PCMD"><img alt="TestFlight" src="https://img.shields.io/badge/TestFlight-%E6%B5%8B%E8%AF%95%E7%89%88-0D96F6?style=for-the-badge&logo=apple&logoColor=white"></a>
+</p>
 
-## 下载 AI-HUB 手机 App
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-mobile-plugin"><img alt="npm" src="https://img.shields.io/npm/v/dsh-mobile-plugin?style=flat-square"></a>
+  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square">
+  <img alt="platform" src="https://img.shields.io/badge/platform-iOS%20%7C%20Android-999999?style=flat-square">
+  <a href="EN-README.md"><img alt="English" src="https://img.shields.io/badge/README-English-2f81f7?style=flat-square"></a>
+</p>
 
+<p align="center">电脑上开着的 DSH，手机上接着用。</p>
+
+**AI-HUB 的手机端插件。** 装在电脑这边，手机 App 就通过一条中转隧道或局域网配对连进你的 DSH —— 看会话、接着聊、管理文件和工作区，进度实时同步。它也可以脱离桌面外壳单独跑在服务器上，当作无头宿主用。
+
+## 🌟 功能
+
+- 🚀 **两种连法**：经 relay v2 隧道从公网连回来，或者在同一个 Wi-Fi 下走局域网代理直连。
+- 📱 **受限的移动 API**：`/api/mobile/v1/*` 只开手机需要的口子 —— 不暴露 shell、系统设置与任意文件写入。
+- 🗂️ **会话与工作区**：新建会话、归入指定工作区，手机端排的顺序也会同步回电脑。
+- 📡 **实时事件**：设备事件 SSE 全程转发，手机上看到的就是电脑那边的进度。
+- 🧹 **自动归档**：闲置会话自动收进归档，只从列表里隐藏，日志不删。
+- 🔐 **配对与凭据**：本机配置接口、可选的配对策略，设备凭据可以单独吊销。
+
+## 📥 下载 AI-HUB 手机 App
+
+- [App Store](https://apps.apple.com/us/app/ai-hub/id6821681438)（正式版，已在架）
 - [Android APK](https://app.wnluo.com/public/apps/14)
 - [Android APK（GitHub 渠道）](https://github.com/WNLUO/dsh-mobile-plugin/releases/latest/download/ai-hub-android.apk)；[历史版本](https://github.com/WNLUO/dsh-mobile-plugin/releases)
-- [App Store](https://apps.apple.com/us/app/ai-hub/id6821681438)（若暂时无法打开，可能是 App 仍在等待苹果审核通过。）
-- [TestFlight 测试版](https://testflight.apple.com/join/4fn5PCMD)
-
-## 功能
+- [TestFlight 测试版](https://testflight.apple.com/join/4fn5PCMD)（比商店版先拿到新构建，正式版照常从 App Store 更新）
 
-- 通过 relay v2 隧道连接手机 App，并支持局域网代理。
-- 提供受限的 `/api/mobile/v1/*` 移动 API。
-- 支持会话创建、工作区归属与会话排序同步。
-- 支持设备事件 SSE 转发、自动归档和会话清理。
-- 提供本机配置接口与配对授权策略。
+装好 App 只有一半，另一半是这个插件。
 
-## 安装与使用
+## 🚀 安装与更新
 
-### 在 DSH 桌面端
+### 桌面端
 
-在 DSH 的 **设置 → 插件** 中搜索并安装 `dsh-mobile-plugin`。安装后，从 **设置 → 移动端 → 打开配置页面** 配置连接与配对。插件市场负责检查和安装更新；通常更新后无需重启 DSH。
+在 DSH 的 **设置 → 插件** 里搜索并安装 `dsh-mobile-plugin`，然后打开 **设置 → 移动端 → 打开配置页面** 做配对。插件市场负责检查和安装更新，通常更新后不用重启 DSH。
 
 ### 无头 Host（Linux）
 
-需要 Node.js、pnpm，以及可用的 DSH 插件宿主依赖。仓库提供 `host.js` 作为独立入口：
+需要 Node.js、pnpm，以及可用的 DSH 插件宿主依赖。仓库里的 `host.js` 就是独立入口：
 
 ```sh
 pnpm install --frozen-lockfile
 DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
 ```
 
-`DSH_HOME` 是数据根目录，默认 `~/.dsh`；`DSH_MOBILE_PROFILE` 是 profile 名称，默认 `mobile`。无头 Host 的 Web 服务默认监听 `127.0.0.1:3080`，不对局域网直接开放。
+`DSH_HOME` 是数据根目录，默认 `~/.dsh`；`DSH_MOBILE_PROFILE` 是 profile 名称，默认 `mobile`。无头 Host 的 Web 服务默认只监听 `127.0.0.1:3080`，不对局域网直接开放。
 
-配置接口仅限本机访问。可用以下地址查看状态和获取配对信息：
+配置接口只限本机访问，看状态和拿配对信息：
 
 ```sh
 curl http://127.0.0.1:3080/api/relay/status
 curl http://127.0.0.1:3080/api/relay/pairing
 ```
 
-更多无头部署方式见下文「无头部署」。
+更多的部署方式见下面的「无头部署」。
 
-## 配置与 API
+## 🔌 配置与 API
 
-无头运行时可通过本机接口管理远程连接：
+无头运行时用这几个本机接口管远程连接：
 
-- `POST /api/relay/toggle`：启用或关闭远程控制。
+- `POST /api/relay/toggle`：开或关远程控制。
 - `POST /api/relay/regenerate`：重新生成配对码。
 - `POST /api/relay/config`：设置 `relayUrl`、`lanEnabled`、`lanPort`、`name` 和 `pairingPolicy`。
-- `POST /api/relay/reconnect`：重新连接隧道与局域网代理。
+- `POST /api/relay/reconnect`：重连隧道与局域网代理。
+
+移动 API 要 Bearer token。设备事件流 `GET /api/mobile/v1/events/stream` 用 SSE 转发宿主事件。建会话时可以传 `workspaceId` 或 `cwd`，前者优先，并会把会话归进那个工作区；手机端的排序同样会同步到宿主工作区。
 
-移动 API 需要 Bearer token。设备事件流 `GET /api/mobile/v1/events/stream` 使用 SSE 转发宿主事件。创建会话时可传 `workspaceId` 或 `cwd`；前者优先，并将会话归入指定工作区。移动端排序也会同步到宿主工作区。
+配对策略默认 `code`，凭配对码放行；设成 `deny` 就拒绝所有新配对。
 
-配对策略默认为 `code`（凭配对码放行）；设为 `deny` 时拒绝所有新配对。自动归档只隐藏符合条件的闲置会话，不删除日志。`session_cleanup` 工具可归档会话，也可永久删除已归档会话；删除不可恢复，需要显式确认。删除是「排进待删队列」：会话立刻从列表里消失，日志与投影缓存等宿主下次启动时才从磁盘上删掉 —— 宿主没有「删除会话」的接口，进程活着的时候从它脚底下删文件会让它读到不存在的日志，那是未捕获异常，会带走整个宿主进程。
+`session_cleanup` 工具能归档会话，也能永久删除归档过的会话，删除前要显式确认，删掉不可恢复。**删除是排队的**：会话立刻从列表里消失，日志和投影缓存等宿主下次启动才从磁盘上删 —— 宿主没有「删除会话」的接口，进程活着的时候从它脚底下删文件，它会打开一个已经不在的日志，那是未捕获异常，会带走整个宿主进程。
 
-## 无头部署
+## 🖥️ 无头部署
 
-无头服务器的启动器与插件本体分开管理：启动器由部署流程同步到 `/opt/dsh-mobile/`，插件本体安装在 profile 中：
+无头服务器上，启动器和插件本体是分开管的：启动器由部署流程同步到 `/opt/dsh-mobile/`，插件本体装进 profile：
 
 ```sh
 cd <DSH_HOME>/profiles/<profile>
 pnpm add dsh-mobile-plugin@<版本>
 ```
 
-宿主会优先挂载 profile 中安装的插件；未安装时才使用源码树版本。设备凭据库随 npm 包一同提供，不需要单独安装。仓库锁文件应使用 `pnpm install --frozen-lockfile`。
+宿主优先挂 profile 里装的那份，没装才用源码树版本。设备凭据库随 npm 包一起发，不用单独装。仓库锁文件用 `pnpm install --frozen-lockfile`。
 
-> 不要使用 `npm install --legacy-peer-deps` 安装插件；正式安装请使用 DSH 插件市场。
+> 别用 `npm install --legacy-peer-deps` 装插件；正式安装走 DSH 插件市场。
 
-## 本机调试 OTA
+## 🔄 本机调试 OTA
 
-新版插件的管理面板提供「本机调试 OTA」卡片，可手动检查并安装中转发布的紧急完整包。入口仅限宿主本机访问，不会由手机或公网触发；安装后通过实现代切换生效，切换失败会恢复上一代。npm 仍是正式发布源；后续 npm 正式版本达到 OTA 版本时会接管该版本。首次发布带此功能的 npm 包需要重启一次 DSH，让稳定外壳加载 OTA 能力。
+新版插件的管理面板里有张「本机调试 OTA」卡片，可以手动检查并安装中转发布的紧急完整包。入口只认宿主本机的访问，手机和公网都触发不了；装完靠切换实现代生效，切换失败会退回上一代。正式发布源仍然是 npm，等 npm 上的版本号追到 OTA 版本时就自动接管。第一次发带这个功能的 npm 包需要重启一次 DSH，让稳定外壳把 OTA 能力加载进来。
 
-发布一个紧急完整包：用仓库里的打包脚本，不要手工 `tar`。
+要发一个紧急完整包，用仓库里的打包脚本，别手工 `tar`：
 
 ```sh
 # 只打包（产物在当前目录）
@@ -85,37 +108,37 @@ node scripts/pack-ota.mjs
 node scripts/pack-ota.mjs --publish https://你的中转 --token <中转的 OTA 发布 token>
 ```
 
-脚本做四件事：文件清单问 `npm pack --dry-run --json` 要（**不碰系统 tar**，三个平台同一份逻辑）、往包里写一份 `lib/ota-manifest.json`（版本 + 每个文件的路径与字节数）、用客户端的真解包器自检、发布后再下载回来比 sha256。中转那边也记哈希，客户端装之前会核对——半个包、被中间层改过的包都装不上去。
+脚本干四件事：文件清单问 `npm pack --dry-run --json` 要（**不碰系统 tar**，三个平台同一份逻辑）、往包里写一份 `lib/ota-manifest.json`（版本 + 每个文件的路径与字节数）、用客户端的真解包器自检、发布后再下载回来比 sha256。中转那边也记哈希，客户端装之前会核对 —— 半个包、被中间层改过的包都装不上去。
 
 `--platform` 默认 `process.platform`（`darwin` / `linux` / `win32`）；这个插件是纯 JS，也可以 `--platform any` 发一份三个系统通用，客户端在自己平台没有包时会回落去问 `any`。`channel` 一般 `stable`。发布接口没配 token 时是关闭的，下载不受影响；版本按号比，最后发的那个才是「最新」。
 
-## 开发
+## 👨‍💻 开发
 
 ```sh
 pnpm install --frozen-lockfile
 npm test
 ```
 
-修改 `React/` 面板源码后，先在该目录运行 `pnpm run build`，并将生成的 `lib/panel/index.html` 与源码一起提交。
+改过 `React/` 面板源码，先在该目录跑 `pnpm run build`，并把生成的 `lib/panel/index.html` 和源码一起提交。
 
-## 仓库与发布
+## 📦 仓库与发布
 
-本仓库是插件的公开发布仓库，仓库根目录就是 npm 包根目录。开发与 App、中转服务器位于私有 monorepo，因此公开仓库的提交历史从拆分时开始；发布时需将同一次改动同步到公开仓库。
+这里是插件的公开发布仓库，仓库根就是 npm 包根。开发和 App、中转服务器一起放在私有 monorepo 里，所以这个仓库的提交历史从拆分那天开始；发布时要把同一次改动同步过来。
 
-- npm 包的 `repository` 字段用于关联插件列表条目；修改后需再次发布，注册表信息才会更新。
-- 插件列表收录通过向 awesome-dsh-plugin 提交 `data/plugins/<owner>__<repo>.yml` 完成。描述中的数字和 API 名称应能由代码核实；列表要求 `description.en`、`category: remote`，包需声明 `dsh.bundle`，仓库需有 `dsh-plugin` topic。
-- 仓库创建满一天的检查会自动重跑；截图可通过 `screenshots.json` 提供，也可由市场从 README 查找。
-- GitHub 的 release 页放手机 App 的 APK（下载入口见开头那一节）：资产名固定用 `ai-hub-android.apk`，并且发成正式版 —— 草稿与预发布都不会成为「最新」，README 里那条直连会随之断掉。插件自身走 npm 发布，不在本仓库发 release。
+- npm 包的 `repository` 字段负责关联插件列表条目，改完要再发一次版，注册表里的信息才会更新。
+- 收录靠往 awesome-dsh-plugin 提 `data/plugins/<owner>__<repo>.yml`。描述里的数字和 API 名称都要能在代码里核实；列表要求 `description.en`、`category: remote`，包要声明 `dsh.bundle`，仓库要有 `dsh-plugin` topic。
+- 「仓库创建满一天」这条检查过一阵会自己重跑。截图可以用 `screenshots.json` 提供，也可以让市场从这个 README 里找。
+- GitHub 的 release 页放手机 App 的 APK（下载入口见开头那一节）：资产名固定用 `ai-hub-android.apk`，而且要发成正式版 —— 草稿和预发布都不会成为「最新」，README 里那条直连跟着就断了。插件自己走 npm 发布，不在这个仓库发 release。
 - 隐私政策：[PRIVACY.md](PRIVACY.md)。技术支持与常见问题：[SUPPORT.md](SUPPORT.md)。
 
-### 发布新版本
+### 发版流程
 
-1. 运行 `node scripts/bump-version.mjs` 更新版本号。
-2. 若修改了 `React/`，运行 `cd React && pnpm run build`。
-3. 运行 `npm test`，并用 `npm pack --dry-run` 检查发布文件。
-4. 运行 `npm publish`，按提示完成 npm 二次验证。
-5. 用 `npm view dsh-mobile-plugin version` 确认注册表版本，再同步改动到公开仓库。
+1. 跑 `node scripts/bump-version.mjs` 更新版本号。
+2. 改过 `React/` 就跑 `cd React && pnpm run build`。
+3. 跑 `npm test`，再用 `npm pack --dry-run` 看一眼要发出去的文件。
+4. 跑 `npm publish`，按提示完成 npm 二次验证。
+5. 用 `npm view dsh-mobile-plugin version` 确认注册表版本，再把改动同步到公开仓库。
 
-## 远程控制元数据
+## 📎 远程控制元数据
 
-配对请求可携带设备信息，App 当前发送 `id`、`deviceId`、`name`、`platform`、`osVersion` 和 `appVersion`；局域网代理与中转会补充观察到的手机 IP。
+配对请求可以带设备信息，App 现在会发 `id`、`deviceId`、`name`、`platform`、`osVersion` 和 `appVersion`；局域网代理与中转会补上它们观察到的手机 IP。

package/config/agent-presets/standard/agent.cordis.yml

@@ -171,3 +171,16 @@
   # disables the whole row — rather than degrade — when one does not match.
   - id: tool-ask-user
     name: '@deepseek-ai/dsh-tool-ask-user'
+  # `present` 是模型**显式声明交付文件**的那一行。桌面 `standard` preset 里一直有它
+  # （`@deepseek-ai/dsh-web-app/presets/standard.patch.yml`），手机这份漏了 —— 于是手机
+  # 上的模型完全没有「把文件交付给用户」这个动作，只能写完文件什么也不说；App 那边只好
+  # 拿 write/edit 成功去反推，结果「每改一次都冒一张卡、用命令行改的却一张都没有」。
+  #
+  # 它只做两件事：校验路径是会话文件系统里真实存在的普通文件，然后把
+  # `deliverables/presented` 事件追加进会话日志。卡片该不该出现，由**模型叫不叫这个工具**
+  # 决定，不由「有没有文件被改」决定 —— 这是桌面的口径。
+  #
+  # 版本必须钉在运行时那一代（当前 0.2.1-rc.2）：它的 peerDependencies 逐版本紧咬，
+  # 对不上时 `dsh-app-boot` 会**整行禁用**（不是降级），现象是模型说「没有这个工具」。
+  - id: tool-present
+    name: '@deepseek-ai/dsh-tool-present'

package/dsh-mobile-credentials/lib/credentials.js

@@ -117,6 +117,29 @@ function listActive() {
   load();
   return records.filter((record) => !record.revokedAt && (!record.expiresAt || record.expiresAt > Date.now())).map(({ instanceId, deviceId, createdAt, expiresAt }) => ({ instanceId, deviceId, createdAt, ...(expiresAt ? { expiresAt } : {}) }));
 }
+/** 一份镜像最多带这么多条摘要：长期反复配对不该把推送清单撑成累赘。 */
+const MAX_ACTIVE_DIGESTS = 200;
+/**
+ * 本实例签发过、仍然有效的凭据摘要，按签发时间从新到旧。
+ *
+ * 中转的离线镜像缓存要在桌面宿主上线之前判断「来读缓存的人是不是配对过的手机」，而它手上
+ * 只有手机发来的 `dshc_` 原文 —— 这里给出同一口径的 sha256（落盘存的本来就是这个摘要，
+ * 原文从未留存），它自己算一遍就能比对。吊销与过期在这里现读现滤，撤销一台设备后下一次
+ * 推送就少一条。
+ */
+function activeDigests(instanceId) {
+  load();
+  const now = Date.now();
+  const live = [];
+  // 记录只在新签发时追加，所以倒着走就是 createdAt 倒序：超出上限时被截掉的是最老的，
+  // 同毫秒签发的几条也保持签发顺序而不是凭运气。
+  for (let i = records.length - 1; i >= 0 && live.length < MAX_ACTIVE_DIGESTS; i -= 1) {
+    const record = records[i];
+    if (record.instanceId !== instanceId || !isLive(record, now)) continue;
+    live.push({ hash: record.hash, ...(record.expiresAt ? { expiresAt: record.expiresAt } : {}) });
+  }
+  return live;
+}
 function revokeDevice(instanceId, deviceId) {
   load();
   let count = 0;
@@ -132,4 +155,4 @@ function revokeAllByInstance(instanceId) {
   if (count) save();
   return count;
 }
-module.exports = { FILE, DEFAULT_TTL_MS, issue, find, lookup, isLive, isActiveDevice, revoke, revokeDevice, revokeAllByInstance, listActive };
+module.exports = { FILE, DEFAULT_TTL_MS, issue, find, lookup, isLive, isActiveDevice, activeDigests, revoke, revokeDevice, revokeAllByInstance, listActive };

package/lib/git/exec.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * 跑 git、按仓库排队：移动端 Git 能力的唯一进程入口。
+ *
+ * 三条前提：
+ *   1. **不接受外部传进来的命令**。这里只收参数数组，可执行文件写死 `git`，参数由调用方
+ *      拼、值一律走白名单校验（`--` 之后才是路径），所以移动 API 那条「不暴露 shell」的
+ *      边界仍然成立；
+ *   2. **失败不当异常抛**。非零退出是常态（没有上游、坏分支名、钩子拒绝），调用方要拿退出码
+ *      和 stderr 判断，所以一律 resolve 成 `{ code, stdout, stderr }`，只有「git 根本没装」
+ *      与「超时被杀」单独立成 `error` 字段；
+ *   3. **按仓库串行**。手机上一次点两下就会并发两次写，撞上 `.git/index.lock` 会互相踩死；
+ *      锁的粒度是仓库根，主仓库与它下面的独立子仓库各排各的队。
+ *
+ * 环境变量按「别挂住、别落锁、别本地化」设：`GIT_TERMINAL_PROMPT=0` 挡住凭据提示（移动请求
+ * 没有 stdin，挂住就只能等超时），`GIT_OPTIONAL_LOCKS=0` 让纯读不顺手刷新索引，
+ * `GIT_PAGER=cat` 免得哪天接了分页器就一直等，`LC_ALL=C` 只是让 stderr 进日志时统一。
+ */
+
+const { execFile } = require('node:child_process');
+
+const BASE_ENV = {
+  ...process.env,
+  GIT_TERMINAL_PROMPT: '0',
+  GIT_PAGER: 'cat',
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_ASKPASS: '',
+  LC_ALL: 'C',
+  LANG: 'C',
+};
+
+const DEFAULT_TIMEOUT_MS = 8000;
+const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+
+/** 仓库根的串行队列：root → 这条链的尾巴（永远是个已收敛的 Promise）。 */
+const chains = new Map();
+
+/**
+ * 在某个仓库的独占队列里跑一段活。读也排队：写操作进行到一半时去读索引，拿到的是半成品。
+ *
+ * @template T
+ * @param {string} root 仓库根（绝对路径）
+ * @param {() => Promise<T>} task
+ * @returns {Promise<T>}
+ */
+function withRepoLock(root, task) {
+  const previous = chains.get(root) || Promise.resolve();
+  const next = previous.then(task, task);
+  // 队列尾巴吞掉失败：一次失败不能把后续排队的活一起带走。
+  chains.set(root, next.then(() => undefined, () => undefined));
+  return next;
+}
+
+/**
+ * 跑一次 git。
+ *
+ * @param {string} root 工作目录（仓库根）
+ * @param {string[]} args 参数数组（不含 `git` 本身）
+ * @param {{ timeoutMs?: number, maxBytes?: number }} [options]
+ * @returns {Promise<{ code: number, error: string|null, stdout: string, stderr: string, truncated: boolean }>}
+ *   `error`：`GIT_UNAVAILABLE`（这台机器没有 git）/ `TIMEOUT` / `TOO_LARGE`；否则为 null。
+ */
+function runGit(root, args, options = {}) {
+  const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBuffer = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  return new Promise((resolve) => {
+    execFile('git', args, {
+      cwd: root,
+      env: BASE_ENV,
+      timeout,
+      maxBuffer,
+      encoding: 'utf8',
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      const out = typeof stdout === 'string' ? stdout : '';
+      const err = typeof stderr === 'string' ? stderr : '';
+      if (!error) {
+        resolve({ code: 0, error: null, stdout: out, stderr: err, truncated: false });
+        return;
+      }
+      if (error.code === 'ENOENT') {
+        resolve({ code: -1, error: 'GIT_UNAVAILABLE', stdout: out, stderr: err, truncated: false });
+        return;
+      }
+      if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+        resolve({ code: -1, error: 'TOO_LARGE', stdout: out, stderr: err, truncated: true });
+        return;
+      }
+      if (error.killed) {
+        resolve({ code: -1, error: 'TIMEOUT', stdout: out, stderr: err, truncated: false });
+        return;
+      }
+      const code = typeof error.code === 'number' ? error.code : -2;
+      resolve({ code, error: null, stdout: out, stderr: err, truncated: false });
+    });
+  });
+}
+
+/** 跑一次 git 并要求成功；失败时带上退出码与 stderr（调用方据此映射错误码）。 */
+async function runGitStrict(root, args, options) {
+  const result = await runGit(root, args, options);
+  if (result.error === 'GIT_UNAVAILABLE') {
+    const failure = new Error('这台电脑上没有可用的 git');
+    failure.code = 'GIT_UNAVAILABLE';
+    throw failure;
+  }
+  if (result.error === 'TIMEOUT') {
+    const failure = new Error('git 超时');
+    failure.code = 'TIMEOUT';
+    throw failure;
+  }
+  if (result.code !== 0) {
+    const failure = new Error((result.stderr || '').trim() || `git 退出码 ${result.code}`);
+    failure.code = 'GIT_FAILED';
+    failure.exitCode = result.code;
+    failure.stderr = result.stderr;
+    throw failure;
+  }
+  return result;
+}
+
+module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  BASE_ENV,
+  runGit,
+  runGitStrict,
+  withRepoLock,
+};

package/lib/git/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/git/parse.js

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * git 机器可读输出的解析：全部是纯函数，喂字符串出结构化数据。
+ *
+ * 为什么不用人能读的那份输出：`git status`、`git log --stat` 这些是给眼睛看的，措辞随版本与
+ * 语言环境变（`LC_ALL=C` 也挡不住措辞在版本间的改动），拿正则去啃迟早会碎。这里只用
+ * `--porcelain=v2 -z` / `--numstat -z` / `--name-status -z` / `for-each-ref` 这些**约定为机器
+ * 输出**的格式，字段之间用 NUL 与 `\x1f` 分隔（文件名里可以有空格、冒号、中文，不能有 NUL）。
+ *
+ * 分隔符约定（都实测过，见 test/git-parse.test.cjs）：
+ *   - `status --porcelain=v2 -z`：状态行以 NUL 结尾；重命名那条（`2` 开头）后面紧跟一个 NUL
+ *     再跟旧路径；
+ *   - `--numstat -z`：正常一条 `增\t删\t路径\0`；重命名的是 `增\t删\t\0旧\0新\0`，路径字段
+ *     为空 —— 空就是「后面还有两个」的信号；
+ *   - `log --numstat -z --format=%x1e%H`：每条提交以 `\x1e` 开头，hash 之后是若干个 numstat
+ *     记录，同样 NUL 结尾；
+ *   - `show --name-status -z`：`状态\0路径\0`，重命名是 `R100\0旧\0新\0`；
+ *   - `for-each-ref`：一条一行，字段之间是 `%00`。
+ */
+
+const NUL = '\0';
+const UNIT = '\x1f';
+const RECORD = '\x1e';
+
+/** 把 NUL 分隔的 numstat 记录切成 `{ path, oldPath, additions, deletions, binary }`。 */
+function parseNumstatZ(text) {
+  const tokens = String(text || '').split(NUL);
+  const out = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    // `--format=` 的提交头后面会跟一个换行，第一条记录因此以 `\n` 开头（实测）。
+    const token = tokens[index].replace(/^\n+/, '');
+    const match = /^(\d+|-)\t(\d+|-)\t(.*)$/.exec(token);
+    if (!match) continue;
+    const binary = match[1] === '-';
+    let path = match[3];
+    let oldPath;
+    if (path === '') {
+      // 重命名：路径字段留空，后面紧跟旧路径与新路径。
+      oldPath = tokens[index + 1] || '';
+      path = tokens[index + 2] || '';
+      index += 2;
+    }
+    if (!path) continue;
+    out.push({
+      path,
+      ...(oldPath ? { oldPath } : {}),
+      additions: binary ? 0 : Number(match[1]),
+      deletions: binary ? 0 : Number(match[2]),
+      binary,
+    });
+  }
+  return out;
+}
+
+/**
+ * 解析 `status --porcelain=v2 -z --branch`：返回状态条目与分支头信息。
+ *
+ * 条目里 `x` 是索引相对 HEAD 的状态（已暂存那批），`y` 是工作区相对索引的状态（未暂存那批），
+ * 未跟踪是 `?`，冲突是 `u` 那条。
+ */
+function parseStatusZ(text) {
+  const tokens = String(text || '').split(NUL);
+  const entries = [];
+  const branch = { head: null, oid: null, upstream: null, ahead: 0, behind: 0 };
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token) continue;
+    const kind = token[0];
+    if (kind === '#') {
+      const [, key, ...rest] = token.split(' ');
+      const value = rest.join(' ');
+      if (key === 'branch.head') branch.head = value === '(detached)' ? null : value;
+      else if (key === 'branch.oid') branch.oid = value === '(initial)' ? null : value;
+      else if (key === 'branch.upstream') branch.upstream = value;
+      else if (key === 'branch.ab') {
+        const match = /\+(-?\d+) -(-?\d+)/.exec(value);
+        if (match) {
+          branch.ahead = Number(match[1]);
+          branch.behind = Number(match[2]);
+        }
+      }
+      continue;
+    }
+    if (kind === '?') {
+      entries.push({ path: token.slice(2), x: '?', y: '?', untracked: true });
+      continue;
+    }
+    if (kind === '!') continue;
+    if (kind === '1' || kind === 'u') {
+      const fields = kind === '1'
+        ? /^1 (\S{2}) \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/.exec(token)
+        : /^u (\S{2}) \S+ \S+ \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/.exec(token);
+      if (!fields) continue;
+      entries.push({
+        path: fields[2],
+        x: fields[1][0],
+        y: fields[1][1],
+        ...(kind === 'u' ? { conflicted: true } : {}),
+      });
+      continue;
+    }
+    if (kind === '2') {
+      const fields = /^2 (\S{2}) \S+ \S+ \S+ \S+ \S+ \S+ \S+ (.*)$/.exec(token);
+      if (!fields) continue;
+      entries.push({
+        path: fields[2],
+        oldPath: tokens[index + 1] || '',
+        x: fields[1][0],
+        y: fields[1][1],
+      });
+      index += 1;
+    }
+  }
+  return { entries, branch };
+}
+
+/** 解析 `--name-status -z`（提交详情里的文件清单）：`状态\0路径\0`，重命名多一个旧路径。 */
+function parseNameStatusZ(text) {
+  const tokens = String(text || '').split(NUL);
+  const out = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const status = tokens[index];
+    if (!status) continue;
+    if (status[0] === 'R' || status[0] === 'C') {
+      const oldPath = tokens[index + 1] || '';
+      const path = tokens[index + 2] || '';
+      index += 2;
+      if (path) out.push({ status: status[0], path, oldPath });
+      continue;
+    }
+    const path = tokens[index + 1] || '';
+    index += 1;
+    if (path) out.push({ status: status[0], path });
+  }
+  return out;
+}
+
+/**
+ * 解析统一格式的 diff 文本成 hunk 列表（行号由插件算好，前端不再数）。
+ *
+ * `` 那种提示行丢掉：它不占行号，留着只会让前端画出一条空行。
+ */
+function parseDiffText(text) {
+  const lines = String(text || '').split('\n');
+  // 末尾那个换行会切出一个空串；不先摘掉它，最后一个 hunk 会多画一行空上下文。
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  const hunks = [];
+  let current = null;
+  let oldLine = 0;
+  let newLine = 0;
+  let binary = false;
+  for (const line of lines) {
+    if (line.startsWith('Binary files ') || line.startsWith('GIT binary patch')) {
+      binary = true;
+      continue;
+    }
+    const header = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@(.*)$/.exec(line);
+    if (header) {
+      oldLine = Number(header[1]);
+      newLine = Number(header[2]);
+      current = { header: line, lines: [] };
+      hunks.push(current);
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith('\\')) continue;
+    if (line.startsWith('+')) {
+      current.lines.push({ kind: 'add', text: line.slice(1), oldLine: null, newLine });
+      newLine += 1;
+      continue;
+    }
+    if (line.startsWith('-')) {
+      current.lines.push({ kind: 'del', text: line.slice(1), oldLine, newLine: null });
+      oldLine += 1;
+      continue;
+    }
+    if (line.startsWith(' ')) {
+      current.lines.push({ kind: 'context', text: line.slice(1), oldLine, newLine });
+      oldLine += 1;
+      newLine += 1;
+    }
+  }
+  return { hunks, binary };
+}
+
+/**
+ * 解析 `log --numstat -z --format=%x1e%H%x1f%h%x1f%an%x1f%aI%x1f%s`：
+ * 每条提交以 `\x1e` 开头，第一段是按 `\x1f` 切开的元信息，后面是本条提交的 numstat 记录。
+ */
+function parseLogZ(text) {
+  const blocks = String(text || '').split(RECORD);
+  const commits = [];
+  for (const block of blocks) {
+    const trimmed = block.replace(/^\n/, '');
+    if (!trimmed) continue;
+    const [head, ...stats] = trimmed.split(NUL);
+    const fields = head.split(UNIT);
+    if (fields.length < 5) continue;
+    const [hash, shortHash, author, time, subject] = fields;
+    const files = parseNumstatZ(stats.join(NUL));
+    commits.push({
+      hash,
+      shortHash,
+      author,
+      time,
+      subject,
+      filesChanged: files.length,
+      additions: files.reduce((sum, file) => sum + file.additions, 0),
+      deletions: files.reduce((sum, file) => sum + file.deletions, 0),
+    });
+  }
+  return commits;
+}
+
+/** 解析 `for-each-ref --format=%(refname:short)%00…`：一条一行，字段之间是 NUL。 */
+function parseRefList(text) {
+  return String(text || '')
+    .split('\n')
+    .map((line) => line.split(NUL))
+    .filter((fields) => fields.length >= 2 && fields[0])
+    .map((fields) => ({ name: fields[0], upstream: fields[1] || '', shortHash: fields[2] || '', time: fields[3] || '' }));
+}
+
+/**
+ * `%(upstream:track)` 是 git 给眼睛看的一行（`[ahead 1, behind 2]`），只认 ahead/behind 两个
+ * 数字：措辞可能随版本变，数字不会。拿不到就返回空串，界面按「没上游」处理。
+ */
+function parseTrack(text) {
+  const match = /ahead (\d+)/.exec(String(text || ''));
+  const behind = /behind (\d+)/.exec(String(text || ''));
+  if (!match && !behind) return null;
+  return { ahead: match ? Number(match[1]) : 0, behind: behind ? Number(behind[1]) : 0 };
+}
+
+module.exports = {
+  NUL,
+  UNIT,
+  RECORD,
+  parseNumstatZ,
+  parseStatusZ,
+  parseNameStatusZ,
+  parseDiffText,
+  parseLogZ,
+  parseRefList,
+  parseTrack,
+};