dsh-github-flow 0.1.3 → 0.1.5

package/lib/main.d.ts

@@ -1,4 +1,22 @@
+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'];
-export declare function apply(ctx: any): void;
+export type Config = PluginConfig;
+/**
+ * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
+ */
+export declare const Config: {
+    '~standard': {
+        version: number;
+        vendor: string;
+        validate(value: unknown): {
+            value: PluginConfig;
+        };
+    };
+};
+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,15 +6,47 @@ 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'];
-export function apply(ctx) {
-    const executor = new GhExecutor();
-    // 1. 注册人类 Slash 命令 (/gh status, /gh help)
+/**
+ * 符合 Standard Schema / Cordis Loader 契约的 Config 运行时校验规范
+ */
+export const Config = {
+    '~standard': {
+        version: 1,
+        vendor: 'dsh',
+        validate(value) {
+            const cfg = (typeof value === 'object' && value !== null) ? value : {};
+            return {
+                value: {
+                    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,
+                }
+            };
+        }
+    }
+};
+export function apply(ctx, config = {}) {
+    const executor = new GhExecutor(config);
+    // 1. 兑现生态服务契约：将 GitHub 执行引擎作为服务暴露给其他 DSH 插件 (ctx.github)
+    if (ctx.provide && typeof ctx.provide === 'function') {
+        ctx.provide('github', executor);
+    }
+    else {
+        ctx.github = executor;
+    }
+    // 2. 注册人类 Slash 命令 (/gh status, /gh help)
     if (ctx.commands) {
         registerGhCommand(ctx.commands, executor);
     }
-    // 2. 注册 Agent 模型工具集（5 大核心领域工具）
+    // 3. 注册 Agent 模型工具集（5 大核心领域工具）
     if (ctx.tools) {
         ctx.tools.register(createPrTool(executor));
         ctx.tools.register(createIssueTool(executor));
@@ -22,9 +54,13 @@ export function apply(ctx) {
         ctx.tools.register(createRepoTool(executor));
         ctx.tools.register(createApiTool(executor));
     }
-    // 3. 注册面向 Client 端的 WebServer HTTP 路由
+    // 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/tools/repo.js

@@ -54,16 +54,22 @@ export function createRepoTool(executor) {
             switch (args.action) {
                 case 'view': {
                     let repoTarget = args.repo;
+                    let meta = null;
                     if (!repoTarget) {
-                        const meta = await executor.getRepoMetadata(cwd);
+                        meta = await executor.getRepoMetadata(cwd);
                         if (meta?.nameWithOwner) {
                             repoTarget = meta.nameWithOwner;
                         }
                     }
                     const repoArgs = repoTarget ? [repoTarget] : [];
                     const res = await executor.run(['repo', 'view', ...repoArgs, '--json', 'nameWithOwner,description,defaultBranchRef,isPrivate,stargazerCount,forkCount,url'], { cwd });
-                    if (!res.ok)
+                    if (!res.ok) {
+                        // 若执行 gh 失败（如离线或环境限制），但本地已成功识别仓库元数据，进行优雅兜底返回
+                        if (meta && meta.nameWithOwner) {
+                            return normalizeOutput(meta);
+                        }
                         throw new Error(res.error);
+                    }
                     return normalizeOutput(res.data || res.rawOutput);
                 }
                 case 'search_code': {

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[]>;

package/lib/workspace.js

@@ -0,0 +1,136 @@
+/**
+ * 工作区解析的单一数据源。
+ *
+ * 为什么独立成模块：`~/.dsh/storages/workspace.json` 的读取与「会话 ID → 物理路径」的
+ * 反查逻辑原先在 executor.ts 与 api/routes.ts 里各写了一份（routes.ts 内还写了两遍），
+ * 三份实现的字段兜底行为已有细微差异。同一份事实在多个地方各自解析，迟早会出现
+ * 「工具看到的工作区」与「面板显示的工作区」不一致，因此收敛到这里。
+ *
+ * 本模块刻意不依赖 GhExecutor，只做纯文件读取，便于单元测试与复用。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** 缓存时长：workspace.json 变更频率低，但面板会反复读取，缓存可显著降低磁盘 IO 与解析开销 */
+const WORKSPACE_CACHE_TTL_MS = 5_000;
+let cache = null;
+/** 仅供测试与配置变更后失效使用 */
+export function resetWorkspaceCache() {
+    cache = null;
+}
+export function workspaceJsonPath() {
+    return path.join(os.homedir(), '.dsh', 'storages', 'workspace.json');
+}
+/**
+ * 读取全部工作区记录。
+ * 返回空数组表示「文件不存在」，抛错表示「文件存在但无法解析」——调用方必须区分这两种情况，
+ * 否则 workspace.json 损坏时会显示成「你没有工作区」，把故障伪装成正常空状态。
+ */
+export function readWorkspaces(options = {}) {
+    const now = Date.now();
+    if (!options.bypassCache && cache && now - cache.at < WORKSPACE_CACHE_TTL_MS) {
+        return cache.records;
+    }
+    const file = workspaceJsonPath();
+    if (!fs.existsSync(file)) {
+        cache = { at: now, records: [] };
+        return [];
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const raw = parsed?.tables?.workspaces ?? {};
+    const records = Object.keys(raw).map((id) => {
+        const item = raw[id] ?? {};
+        return {
+            id,
+            title: typeof item.title === 'string' ? item.title : '',
+            path: typeof item.path === 'string' ? item.path : '',
+            sessionIds: Array.isArray(item.sessionIds) ? item.sessionIds : [],
+            updatedAt: typeof item.updatedAt === 'string' ? item.updatedAt : '',
+        };
+    });
+    cache = { at: now, records };
+    return records;
+}
+/** 容错读取：读取失败时返回空数组并把原因交给调用方，绝不静默吞掉 */
+export function tryReadWorkspaces() {
+    try {
+        return { workspaces: readWorkspaces() };
+    }
+    catch (err) {
+        return { workspaces: [], error: err?.message || '工作区数据读取失败' };
+    }
+}
+/**
+ * 按会话 ID 反查物理工作区路径。
+ * 命中要求路径真实存在——workspace.json 里可能残留已删除的目录。
+ */
+export function findWorkspacePathBySession(sessionId) {
+    try {
+        const { workspaces } = tryReadWorkspaces();
+        for (const ws of workspaces) {
+            if (ws.sessionIds.includes(sessionId) && ws.path && fs.existsSync(ws.path)) {
+                return ws.path;
+            }
+        }
+    }
+    catch {
+        // 会话反查是可选的尽力而为路径，失败时由调用方回退到其他策略
+    }
+    return undefined;
+}
+/**
+ * 匹配最近活跃的工作区路径。
+ * 注意 updatedAt 可能缺失或非 ISO 格式，统一用时间戳比较，无效值视为 0 而非 NaN——
+ * 后者会让所有比较都返回 false，导致永远选不中任何工作区。
+ */
+export function findMostRecentWorkspacePath() {
+    try {
+        const { workspaces } = tryReadWorkspaces();
+        let best = null;
+        let bestAt = -1;
+        for (const ws of workspaces) {
+            const at = Date.parse(ws.updatedAt || '');
+            const score = Number.isFinite(at) ? at : 0;
+            if (score > bestAt && ws.path && fs.existsSync(ws.path)) {
+                best = ws;
+                bestAt = score;
+            }
+        }
+        return best?.path;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasGitDir(dir) {
+    try {
+        return fs.existsSync(path.join(dir, '.git'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 有界并发 map。
+ * 为什么必须有：每个工作区探测最多 spawn 2 个 gh 进程，而 Node 的 libuv 线程池默认只有 4 个
+ * 线程可用。工作区一多，无上限的 Promise.all 会把进程全部排进队列，单次 spawn 超时 10s × 排队
+ * 造成整体秒级到十几秒的延迟（实测 /api/github/global-overview 曾达 18.9s）。
+ * 这里显式限制在途数量，让延迟可预期，而不是随工作区数量线性劣化。
+ */
+export async function mapLimit(items, limit, fn) {
+    if (items.length === 0)
+        return [];
+    const effectiveLimit = Math.max(1, Math.min(limit, items.length));
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: effectiveLimit }, async () => {
+        for (;;) {
+            const index = cursor++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-github-flow",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "icon": "icon.svg",
   "description": "GitHub Flow: Native GitHub CLI (gh) integration for DeepSeek Harness — Agent Tools, Slash Commands, and Web UI Workspace",
   "type": "module",
@@ -55,6 +55,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
     "@types/node": "^26.6.3",
     "typescript": "^7.0.2"
   }