dsh-github-flow 0.1.4 → 0.1.5

package/lib/executor.js

@@ -2,24 +2,119 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
+import { findMostRecentWorkspacePath, findWorkspacePathBySession, hasGitDir } from './workspace.js';
 const execFileAsync = promisify(execFile);
+/** 认证状态缓存时长。用户手动 `gh auth login/logout` 后最多 30 秒内面板才会反映，属可接受代价 */
+const AUTH_CACHE_TTL_MS = 30_000;
+/**
+ * 按码点安全截取字符串，等价于 String.prototype.slice 但对孤立的代理对（surrogate pair）做占位替换。
+ * 为什么必须这样截：本文件末尾会按 UTF-8 字节数截断，而 node:child_process 把 stdout 按字节缓冲区
+ * 切分后再 toString('utf8')，一个汉字被从中间切开时会变成 U+FFFD 替换字符。直接用 slice 会把半截
+ * 代理对留在结果里，导致下游 JSON.stringify 产出孤立转义序列、写入文件时编码报错。
+ */
+function safeSlice(input, start, end) {
+    const chars = Array.from(input);
+    const from = Math.max(0, start);
+    const to = end === undefined ? chars.length : Math.max(from, end);
+    return chars.slice(from, to).map((c) => (c.length === 1 && c.charCodeAt(0) >= 0xd800 && c.charCodeAt(0) <= 0xdfff ? '\ufffd' : c)).join('');
+}
+/**
+ * 以 UTF-8 字节数（而非字符串长度）为口径，从两端保留内容。
+ * 为什么需要：maxOutputChars 数的是字符，中文一个字占 3 字节。只按字符限长时，
+ * 中文环境下真实放行的字节量可达标称值的数倍，Token 预算保护会失真。
+ * 采用二分查找定位截断点，避免对超大输出逐字符累加造成 O(n) 反复编码。
+ */
+function cutByUtf8Bytes(input, headBytes, tailBytes) {
+    const encoder = new TextEncoder();
+    const totalBytes = encoder.encode(input).length;
+    if (totalBytes <= headBytes + tailBytes) {
+        return { head: input, tail: '', keptHeadBytes: totalBytes, keptTailBytes: 0, truncated: false };
+    }
+    const chars = Array.from(input);
+    const atByte = (limit, fromEnd) => {
+        let lo = 0;
+        let hi = chars.length;
+        let bytes = 0;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            const slice = fromEnd ? chars.slice(chars.length - mid) : chars.slice(0, mid);
+            const size = encoder.encode(slice.join('')).length;
+            if (size <= limit) {
+                lo = mid;
+                bytes = size;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return { count: lo, bytes };
+    };
+    const headPart = atByte(headBytes, false);
+    const tailPart = atByte(tailBytes, true);
+    return {
+        head: safeSlice(input, 0, headPart.count),
+        tail: safeSlice(input, chars.length - tailPart.count),
+        keptHeadBytes: headPart.bytes,
+        keptTailBytes: tailPart.bytes,
+        truncated: true,
+    };
+}
+/**
+ * 按「字符数 + UTF-8 字节数」双口径截断输出。
+ * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
+ * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
+ */
+export function truncateOutput(input, maxChars, maxBytes) {
+    // 双重口径限长：字符数守住 Token 预算，字节数守住真实传输量。
+    // 中文场景下两者会分别触发，因此两条路径的提示文案必须区分，避免用户按错误的配置项去调参。
+    if (input.length > maxChars) {
+        // 保留前 1/3 字符和尾部 1/2 字符，保留开头上下文和错误尾部
+        const headLen = Math.floor(maxChars * 0.35);
+        const tailLen = Math.floor(maxChars * 0.55);
+        const head = safeSlice(input, 0, headLen);
+        const tail = safeSlice(input, input.length - tailLen);
+        return {
+            text: `${head}\n\n... [⚠️ 提示：内容过长已由 DSH GitHub 插件截断中间部分，当前截取前 ${Math.round(headLen / 1024)}KB 与后 ${Math.round(tailLen / 1024)}KB] ...\n\n${tail}`,
+            truncated: true,
+        };
+    }
+    const byteCut = cutByUtf8Bytes(input, Math.floor(maxBytes * 0.35), Math.floor(maxBytes * 0.55));
+    if (byteCut.truncated) {
+        // 这里必须用「实际保留的字节数」而非 maxChars 推导值：字节口径触发时 maxChars 往往远大于
+        // 字节上限，早先版本照抄字符分支的算法，会报出与实际严重不符的「已保留 100KB」（实际仅数百字节）。
+        return {
+            text: `${byteCut.head}\n\n... [⚠️ 提示：内容超出 UTF-8 字节上限 (${maxBytes} bytes) 已截断中间部分，实际保留前 ${byteCut.keptHeadBytes} 字节与后 ${byteCut.keptTailBytes} 字节；如需放宽请调大配置项 maxOutputBytes] ...\n\n${byteCut.tail}`,
+            truncated: true,
+        };
+    }
+    return { text: input, truncated: false };
+}
 export class GhExecutor {
     ghPath;
     defaultTimeoutMs;
     maxOutputChars;
+    /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
+    maxOutputBytes;
+    /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
+    authCache = null;
     constructor(config = {}) {
         this.ghPath = config.ghPath || 'gh';
         this.defaultTimeoutMs = config.defaultTimeoutMs || 30_000;
         this.maxOutputChars = config.maxOutputChars || 24_000;
+        this.maxOutputBytes = config.maxOutputBytes || this.maxOutputChars * 4;
     }
     updateConfig(config = {}) {
         if (config.ghPath)
             this.ghPath = config.ghPath;
         if (config.defaultTimeoutMs)
             this.defaultTimeoutMs = config.defaultTimeoutMs;
-        if (config.maxOutputChars)
+        if (config.maxOutputChars) {
             this.maxOutputChars = config.maxOutputChars;
+            if (!config.maxOutputBytes)
+                this.maxOutputBytes = config.maxOutputChars * 4;
+        }
+        if (config.maxOutputBytes)
+            this.maxOutputBytes = config.maxOutputBytes;
     }
     /**
      * 智能解析最可靠的工作区物理路径：
@@ -29,45 +124,20 @@ export class GhExecutor {
      * 4. 回退到 process.cwd()
      */
     resolveWorkspaceCwd(explicitCwd) {
-        if (explicitCwd) {
-            try {
-                if (fs.existsSync(path.join(explicitCwd, '.git'))) {
-                    return explicitCwd;
-                }
-            }
-            catch { }
+        // 显式路径优先，但只认真正含 .git 的目录：调用方传进来的可能是会话根目录而非仓库目录，
+        // 此时继续往下走按会话/最近活跃反查，比盲信传入值更准。
+        if (explicitCwd && hasGitDir(explicitCwd)) {
+            return explicitCwd;
         }
-        try {
-            const wsJsonPath = path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
-            if (fs.existsSync(wsJsonPath)) {
-                const wsData = JSON.parse(fs.readFileSync(wsJsonPath, 'utf8'));
-                const workspaces = wsData.tables?.workspaces || {};
-                // A. 优先通过 DSH 会话 ID 精准匹配物理工作区
-                const sessionId = process.env.DSH_SESSION_ID;
-                if (sessionId) {
-                    for (const wsId of Object.keys(workspaces)) {
-                        const item = workspaces[wsId];
-                        if (item.sessionIds && Array.isArray(item.sessionIds) && item.sessionIds.includes(sessionId)) {
-                            if (item.path && fs.existsSync(item.path)) {
-                                return item.path;
-                            }
-                        }
-                    }
-                }
-                // B. 兜底匹配最近活跃更新的工作区
-                let latestItem = null;
-                for (const wsId of Object.keys(workspaces)) {
-                    const item = workspaces[wsId];
-                    if (!latestItem || new Date(item.updatedAt || 0) > new Date(latestItem.updatedAt || 0)) {
-                        latestItem = item;
-                    }
-                }
-                if (latestItem && latestItem.path && fs.existsSync(latestItem.path)) {
-                    return latestItem.path;
-                }
-            }
+        const sessionId = process.env.DSH_SESSION_ID;
+        if (sessionId) {
+            const bySession = findWorkspacePathBySession(sessionId);
+            if (bySession)
+                return bySession;
         }
-        catch { }
+        const recent = findMostRecentWorkspacePath();
+        if (recent)
+            return recent;
         return explicitCwd || process.cwd();
     }
     /**
@@ -93,16 +163,9 @@ export class GhExecutor {
             if (!rawOutput && stderr) {
                 rawOutput = stderr.trim();
             }
-            let truncated = false;
-            if (rawOutput.length > this.maxOutputChars) {
-                // 保留前 1/3 字符和尾部 1/2 字符，保留开头上下文和错误尾部
-                const headLen = Math.floor(this.maxOutputChars * 0.35);
-                const tailLen = Math.floor(this.maxOutputChars * 0.55);
-                const head = rawOutput.slice(0, headLen);
-                const tail = rawOutput.slice(-tailLen);
-                rawOutput = `${head}\n\n... [⚠️ 提示：内容过长已由 DSH GitHub 插件截断中间部分，当前截取前 ${Math.round(headLen / 1024)}KB 与后 ${Math.round(tailLen / 1024)}KB] ...\n\n${tail}`;
-                truncated = true;
-            }
+            const outcome = truncateOutput(rawOutput, this.maxOutputChars, this.maxOutputBytes);
+            rawOutput = outcome.text;
+            const truncated = outcome.truncated;
             // 如果未被截断且命令带有 --json 或包含 api，尝试解析为 JSON
             if (!options.rawText && !truncated && (args.includes('--json') || args.includes('api'))) {
                 try {
@@ -141,8 +204,26 @@ export class GhExecutor {
     }
     /**
      * 检查宿主机当前 GitHub CLI 的认证状态与账号信息
+     *
+     * @param cwd 解析工作区用的路径
+     * @param bypassCache 跳过进程内缓存。`/gh status` 这类人类显式发起的诊断必须看到实时结果，
+     *   而 Web 面板每次挂载都会来问一次，重复执行实测要 5.4 秒，属于纯浪费。
      */
-    async checkAuth(cwd) {
+    async checkAuth(cwd, bypassCache = false) {
+        const now = Date.now();
+        if (!bypassCache && this.authCache && now - this.authCache.at < AUTH_CACHE_TTL_MS) {
+            return this.authCache.value;
+        }
+        const value = await this.probeAuth(cwd);
+        // 只缓存确定的结果：出错时（未安装/未登录/网络异常）不缓存，
+        // 否则用户 `gh auth login` 之后还要再等满一个 TTL 才能看到面板恢复。
+        if (value.loggedIn) {
+            this.authCache = { at: now, value };
+        }
+        return value;
+    }
+    /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
+    async probeAuth(cwd) {
         const res = await this.run(['auth', 'status'], { cwd, timeoutMs: 10_000, rawText: true });
         const raw = (res.rawOutput || '') + '\n' + (res.error || '');
         const loggedIn = raw.includes('Logged in to') || raw.includes('✓');
@@ -191,6 +272,42 @@ export class GhExecutor {
             raw,
         };
     }
+    /**
+     * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。
+     *
+     * 为什么需要它：全局驾驶舱要为每个工作区认识别仓库，而 getRepoMetadata 会调用
+     * `gh repo view` 走网络。实测 5 个工作区时该端点冷启动 20.5 秒，其中绝大部分耗在这 5 次
+     * 网络往返上——而有界并发根本救不了它，因为瓶颈是网络延迟而不是进程排队。
+     * 工作区矩阵只需要「这个目录属于哪个仓库」这一身份信息，本地 .git/config 已经完整具备，
+     * 描述/star 数等富字段是当前仓库详情才需要的。这一步把每个工作区从 1 次网络往返降为 0。
+     */
+    getRepoIdentityFromLocal(cwd) {
+        const targetCwd = cwd || this.resolveWorkspaceCwd();
+        try {
+            const gitConfigPath = path.join(targetCwd, '.git', 'config');
+            if (!fs.existsSync(gitConfigPath))
+                return null;
+            const configText = fs.readFileSync(gitConfigPath, 'utf8');
+            const match = configText.match(/github\.com[:/]([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?(?:\s|\r|\n|$)/i);
+            if (!match)
+                return null;
+            const owner = match[1];
+            const repoName = match[2];
+            const nameWithOwner = `${owner}/${repoName}`;
+            return {
+                nameWithOwner,
+                name: repoName,
+                owner,
+                defaultBranch: 'main',
+                description: '',
+                isPrivate: false,
+                url: `https://github.com/${nameWithOwner}`,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * 获取当前目录（工作区）关联的远程仓库元数据
      * 采用 gh repo view + 本地 git remote 双保险机制，彻底杜绝已配置远程却误判未关联的问题

package/lib/github-service.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `ctx.github` 服务的 TypeScript 声明合并。
+ *
+ * 为什么需要这个文件：README 教生态插件这样复用本插件的能力——
+ *   export const inject = ['github']
+ *   export function apply(ctx) { await ctx.github.checkAuth() }
+ * 但在此之前项目里没有任何 `declare module` 声明合并，消费方拿到的 `ctx.github`
+ * 类型是 unknown，照文档写会直接编译不过，也没有任何自动补全。
+ * 官方每个服务包（如 @deepseek-ai/dsh-workspace、dsh-commands）都做这件事，这里补齐。
+ *
+ * 消费方用法：import type {} from 'dsh-github-flow/host' —— 或直接 import 本插件导出的任一名，
+ * 只要类型被加载，`ctx.github` 就有完整类型。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { GhExecutor } from './executor.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** 由 dsh-github-flow 提供的 GitHub CLI 执行引擎 */
+        github: GhExecutor;
+    }
+}
+/**
+ * 供消费方做类型引用的空导出。
+ * 目的是让 `import type {} from 'dsh-github-flow'` 能顺带加载上面的声明合并。
+ */
+export type { Context };

package/lib/github-service.js

@@ -0,0 +1 @@
+export {};

package/lib/main.d.ts

@@ -1,4 +1,5 @@
 import { GhExecutor } from './executor.js';
+import './github-service.js';
 import type { PluginConfig } from './types.js';
 export declare const name = "dsh-github-flow";
 export declare const inject: readonly ['tools', 'commands', 'webServer', 'workspaceRegistry'];
@@ -18,3 +19,4 @@ export declare const Config: {
 export declare function apply(ctx: any, config?: PluginConfig): void;
 export type GitHubService = GhExecutor;
 export * from './types.js';
+export * from './github-service.js';

package/lib/main.js

@@ -6,6 +6,9 @@ import { createRepoTool } from './tools/repo.js';
 import { createApiTool } from './tools/api.js';
 import { registerGhCommand } from './commands/gh.js';
 import { registerApiRoutes } from './api/routes.js';
+// 引用即生效：加载本模块以挂上 declare module '@deepseek-ai/cordis' 的 ctx.github 类型声明，
+// 并随下面 `export * from './github-service.js'` 一起传给消费方。
+import './github-service.js';
 export const name = 'dsh-github-flow';
 export const inject = ['tools', 'commands', 'webServer', 'workspaceRegistry'];
 /**
@@ -22,6 +25,7 @@ export const Config = {
                     ghPath: typeof cfg.ghPath === 'string' ? cfg.ghPath : 'gh',
                     defaultTimeoutMs: typeof cfg.defaultTimeoutMs === 'number' ? cfg.defaultTimeoutMs : 30_000,
                     maxOutputChars: typeof cfg.maxOutputChars === 'number' ? cfg.maxOutputChars : 24_000,
+                    maxOutputBytes: typeof cfg.maxOutputBytes === 'number' ? cfg.maxOutputBytes : undefined,
                     cacheTtlMs: typeof cfg.cacheTtlMs === 'number' ? cfg.cacheTtlMs : 15_000,
                     defaultListLimit: typeof cfg.defaultListLimit === 'number' ? cfg.defaultListLimit : 20,
                 }
@@ -52,7 +56,11 @@ export function apply(ctx, config = {}) {
     }
     // 4. 注册面向 Client 端的 WebServer HTTP 路由（如果当前环境启用了 Web UI 服务）
     if (ctx.webServer) {
-        registerApiRoutes(ctx.webServer, executor, ctx.workspaceRegistry);
+        // 传入 ctx 作用域对象，使 routes 能够通过 ctx.effect 绑定生命周期并在插件卸载/重载时自动注销；
+        // cacheTtlMs 传给路由层以尊重用户的缓存 TTL 配置。
+        registerApiRoutes(ctx, executor, ctx.workspaceRegistry, config.cacheTtlMs || 15_000);
     }
 }
 export * from './types.js';
+// 让 `ctx.github` 的类型声明随包一起被消费方加载（声明合并在 './github-service.js' 内）
+export * from './github-service.js';

package/lib/tools/api.d.ts

@@ -22,6 +22,10 @@ export declare function createApiTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            raw: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/lib/tools/api.js

@@ -10,7 +10,7 @@ function normalizeOutput(data) {
 export function createApiTool(executor) {
     return {
         name: 'github_api',
-        description: '通过 GitHub CLI 认证环境直接调用任意 GitHub REST 或 GraphQL API 端点（兜底逃生门）。支持 --jq 过滤。',
+        description: '通过 GitHub CLI 认证环境直接调用任意 GitHub REST 或 GraphQL API 端点（兜底逃生门）。支持 --jq 过滤；fields 一律按字面字符串传参，避免 gh 的 -F 类型转换改写请求体。',
         parameters: {
             type: 'object',
             properties: {
@@ -29,7 +29,11 @@ export function createApiTool(executor) {
                 },
                 fields: {
                     type: 'object',
-                    description: '请求参数或请求体键值对。',
+                    description: '请求参数或请求体键值对。所有值按字面字符串（gh -f）发送，不做布尔/数字类型转换；嵌套对象请先在端点里用 JSON 字段或改用 raw 模式。',
+                },
+                raw: {
+                    type: 'boolean',
+                    description: '是否以原始响应体模式调用（附加 Accept: application/vnd.github.raw 并强制纯文本返回）。默认 false。适用于读取仓库文件内容，避免拿到 base64 编码的一整行。',
                 },
             },
             required: ['endpoint'],
@@ -57,12 +61,27 @@ export function createApiTool(executor) {
             if (args.jq) {
                 cmd.push('--jq', args.jq);
             }
+            if (args.raw === true) {
+                // 让 GitHub 直接返回文件字节而不是 {"content":"<base64>"} 包装。
+                // 没有这个出口时，读任何仓库文件都只能拿到一整行 base64——既不可读，
+                // 又会在超过截断阈值时被从中间切断而彻底无法还原。
+                cmd.push('-H', 'Accept: application/vnd.github.raw');
+            }
             if (args.fields && typeof args.fields === 'object') {
                 for (const [k, v] of Object.entries(args.fields)) {
-                    cmd.push('-F', `${k}=${typeof v === 'object' ? JSON.stringify(v) : v}`);
+                    if (v === undefined || v === null)
+                        continue;
+                    if (typeof v === 'object') {
+                        // 不把嵌套结构 JSON.stringify 后塞进 -F：gh 侧解析结果不可预期，且会静默产出错误请求体。
+                        // 宁可显式报错，让调用方改用 raw 模式或把结构放进端点自身的 JSON 字段。
+                        throw new Error(`github_api 的字段 "${k}" 是嵌套结构，无法作为表单参数发送。请改用 raw 模式传原始 JSON 请求体，或先把该结构序列化后作为字符串字段传入。`);
+                    }
+                    // 用 -f（字面字符串）而非 -F：-F 会做 "true"→布尔、"1"→数字的类型转换，
+                    // 导致字符串请求体被悄悄改写，是跨 fork 提 PR 等场景失败的常见根因。
+                    cmd.push('-f', `${k}=${String(v)}`);
                 }
             }
-            const res = await executor.run(cmd, { cwd });
+            const res = await executor.run(cmd, { cwd, rawText: args.raw === true });
             if (!res.ok)
                 throw new Error(res.error);
             return normalizeOutput(res.data !== undefined ? res.data : res.rawOutput);

package/lib/tools/pr.d.ts

@@ -30,6 +30,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            head: {
+                type: string;
+                description: string;
+            };
             draft: {
                 type: string;
                 description: string;
@@ -44,6 +48,14 @@ export declare function createPrTool(executor: GhExecutor): {
                 enum: string[];
                 description: string;
             };
+            delete_branch: {
+                type: string;
+                description: string;
+            };
+            dry_run: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/lib/tools/pr.js

@@ -39,6 +39,10 @@ export function createPrTool(executor) {
                     type: 'string',
                     description: '目标基准分支（默认主分支，如 main）。',
                 },
+                head: {
+                    type: 'string',
+                    description: '源分支，跨 fork 提 PR 时必填，格式 forkOwner:branch（如 ItQianChen:fix-bug）；同仓库分支可直接写分支名。',
+                },
                 draft: {
                     type: 'boolean',
                     description: '是否创建为草稿 PR。',
@@ -53,6 +57,14 @@ export function createPrTool(executor) {
                     enum: ['merge', 'squash', 'rebase'],
                     description: '合并策略（merge 操作时使用，默认 squash）。',
                 },
+                delete_branch: {
+                    type: 'boolean',
+                    description: '合并后是否删除源分支（merge 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                },
+                dry_run: {
+                    type: 'boolean',
+                    description: '是否只预演不真正创建（create 操作时使用，默认 false）。透传 gh --dry-run：打印将要创建的 PR 详情而不落库，用于提交前确认 head/base/title 是否正确。',
+                },
             },
             required: ['action'],
         },
@@ -112,12 +124,22 @@ export function createPrTool(executor) {
                     const createCmd = ['pr', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
                     if (args.base)
                         createCmd.push('--base', args.base);
+                    // 跨 fork 提 PR 必须显式给出 --head（形如 forkOwner:branch）。
+                    // 为什么不能省：当 -R 指向的仓库不是当前 origin 时，gh 无法推断拿哪个分支开 PR，
+                    // 会逐级回退去问本地 git，最终报出与真实原因无关的 "not a git repository"。
+                    if (args.head)
+                        createCmd.push('--head', args.head);
                     if (args.draft)
                         createCmd.push('--draft');
+                    const dryRun = args.dry_run === true;
+                    if (dryRun)
+                        createCmd.push('--dry-run');
                     const res = await executor.run(createCmd, { cwd });
                     if (!res.ok)
                         throw new Error(res.error);
-                    return { message: 'PR 创建成功', url: res.rawOutput };
+                    return dryRun
+                        ? { message: 'PR 预演完成（未真正创建）', detail: res.rawOutput }
+                        : { message: 'PR 创建成功', url: res.rawOutput };
                 }
                 case 'review': {
                     if (!args.pr_number)
@@ -140,10 +162,15 @@ export function createPrTool(executor) {
                     if (!args.pr_number)
                         throw new Error('merge 操作必须提供 pr_number');
                     const method = args.merge_method === 'merge' ? '--merge' : (args.merge_method === 'rebase' ? '--rebase' : '--squash');
-                    const res = await executor.run(['pr', 'merge', String(args.pr_number), ...repoArgs, method, '--delete-branch'], { cwd });
+                    const mergeCmd = ['pr', 'merge', String(args.pr_number), ...repoArgs, method];
+                    // 删分支默认关闭：合并他人仓库的 PR 时删掉源分支是不可撤销的破坏性动作，
+                    // 而 gh 默认不删。替用户做掉它违背「可撤销的直接做、不可撤销的先问」。
+                    if (args.delete_branch === true)
+                        mergeCmd.push('--delete-branch');
+                    const res = await executor.run(mergeCmd, { cwd });
                     if (!res.ok)
                         throw new Error(res.error);
-                    return { message: 'PR 合并完成并已清理分支', output: res.rawOutput };
+                    return { message: 'PR 合并完成', output: res.rawOutput };
                 }
                 default:
                     throw new Error(`未知的 PR 操作: ${args.action}`);

package/lib/types.d.ts

@@ -8,6 +8,8 @@ export interface PluginConfig {
     defaultTimeoutMs?: number;
     /** 单次安全输出字符数上限（防止 Token 溢出），默认 24,000 */
     maxOutputChars?: number;
+    /** 单次安全输出 UTF-8 字节数硬上限，默认 maxOutputChars × 4（防止中文按字符计数时实际放行字节数倍增） */
+    maxOutputBytes?: number;
     /** Web API 概览数据缓存时长（毫秒），默认 15,000ms */
     cacheTtlMs?: number;
     /** 查询列表默认限制条数，默认 20 */
@@ -151,4 +153,6 @@ export interface GlobalOverviewData {
     }>;
     lastUpdated: string;
     error?: string;
+    /** 工作区矩阵读取失败的原因。区分「没有工作区」与「读不到工作区」，避免把故障显示成空状态 */
+    workspaceError?: string;
 }

package/lib/workspace.d.ts

@@ -0,0 +1,43 @@
+export interface WorkspaceRecord {
+    id: string;
+    title: string;
+    path: string;
+    sessionIds: string[];
+    updatedAt: string;
+}
+/** 仅供测试与配置变更后失效使用 */
+export declare function resetWorkspaceCache(): void;
+export declare function workspaceJsonPath(): string;
+/**
+ * 读取全部工作区记录。
+ * 返回空数组表示「文件不存在」，抛错表示「文件存在但无法解析」——调用方必须区分这两种情况，
+ * 否则 workspace.json 损坏时会显示成「你没有工作区」，把故障伪装成正常空状态。
+ */
+export declare function readWorkspaces(options?: {
+    bypassCache?: boolean;
+}): WorkspaceRecord[];
+/** 容错读取：读取失败时返回空数组并把原因交给调用方，绝不静默吞掉 */
+export declare function tryReadWorkspaces(): {
+    workspaces: WorkspaceRecord[];
+    error?: string;
+};
+/**
+ * 按会话 ID 反查物理工作区路径。
+ * 命中要求路径真实存在——workspace.json 里可能残留已删除的目录。
+ */
+export declare function findWorkspacePathBySession(sessionId: string): string | undefined;
+/**
+ * 匹配最近活跃的工作区路径。
+ * 注意 updatedAt 可能缺失或非 ISO 格式，统一用时间戳比较，无效值视为 0 而非 NaN——
+ * 后者会让所有比较都返回 false，导致永远选不中任何工作区。
+ */
+export declare function findMostRecentWorkspacePath(): string | undefined;
+export declare function hasGitDir(dir: string): boolean;
+/**
+ * 有界并发 map。
+ * 为什么必须有：每个工作区探测最多 spawn 2 个 gh 进程，而 Node 的 libuv 线程池默认只有 4 个
+ * 线程可用。工作区一多，无上限的 Promise.all 会把进程全部排进队列，单次 spawn 超时 10s × 排队
+ * 造成整体秒级到十几秒的延迟（实测 /api/github/global-overview 曾达 18.9s）。
+ * 这里显式限制在途数量，让延迟可预期，而不是随工作区数量线性劣化。
+ */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;