dsh-github-flow 0.1.0

package/lib/tools/pr.js

@@ -0,0 +1,130 @@
+import { defineSafeTool } from './define.js';
+export function createPrTool(executor) {
+    return defineSafeTool({
+        name: 'github_pr',
+        description: '管理与审查 GitHub Pull Request (PR)。支持查看列表、详情、差异比对、CI 检查状态、代码审查与合并操作。默认针对当前工作区关联的仓库。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge'],
+                    description: 'PR 操作类型。',
+                },
+                pr_number: {
+                    type: 'number',
+                    description: 'PR 编号（view, diff, checks, review, merge 时使用；若在 PR 对应分支可不填，自动识别当前分支 PR）。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则自动识别当前本地 Git 仓库。',
+                },
+                title: {
+                    type: 'string',
+                    description: '创建 PR 时的标题。',
+                },
+                body: {
+                    type: 'string',
+                    description: '创建 PR 或提交 Review 时的内容描述。',
+                },
+                base: {
+                    type: 'string',
+                    description: '目标基准分支（默认主分支，如 main）。',
+                },
+                draft: {
+                    type: 'boolean',
+                    description: '是否创建为草稿 PR。',
+                },
+                review_decision: {
+                    type: 'string',
+                    enum: ['APPROVE', 'REQUEST_CHANGES', 'COMMENT'],
+                    description: '代码审查意见判定（review 操作时使用）。',
+                },
+                merge_method: {
+                    type: 'string',
+                    enum: ['merge', 'squash', 'rebase'],
+                    description: '合并策略（merge 操作时使用，默认 squash）。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const repoArgs = args.repo ? ['-R', args.repo] : [];
+            switch (args.action) {
+                case 'list': {
+                    const res = await executor.run(['pr', 'list', ...repoArgs, '--json', 'number,title,author,headRefName,isDraft,state,updatedAt', '-L', '20'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'view': {
+                    const target = args.pr_number ? [String(args.pr_number)] : [];
+                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'checks': {
+                    const target = args.pr_number ? [String(args.pr_number)] : [];
+                    const res = await executor.run(['pr', 'checks', ...target, ...repoArgs, '--json', 'name,state,conclusion,detailsUrl'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'diff': {
+                    const target = args.pr_number ? [String(args.pr_number)] : [];
+                    const res = await executor.run(['pr', 'diff', ...target, ...repoArgs], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.rawOutput || '无差异内容';
+                }
+                case 'create': {
+                    const createCmd = ['pr', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
+                    if (args.base)
+                        createCmd.push('--base', args.base);
+                    if (args.draft)
+                        createCmd.push('--draft');
+                    const res = await executor.run(createCmd, { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: 'PR 创建成功', url: res.rawOutput };
+                }
+                case 'review': {
+                    if (!args.pr_number)
+                        throw new Error('review 操作必须提供 pr_number');
+                    const reviewCmd = ['pr', 'review', String(args.pr_number), ...repoArgs];
+                    if (args.review_decision === 'APPROVE')
+                        reviewCmd.push('--approve');
+                    else if (args.review_decision === 'REQUEST_CHANGES')
+                        reviewCmd.push('--request-changes');
+                    else
+                        reviewCmd.push('--comment');
+                    if (args.body)
+                        reviewCmd.push('--body', args.body);
+                    const res = await executor.run(reviewCmd, { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: 'Review 提交成功', detail: res.rawOutput };
+                }
+                case 'merge': {
+                    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 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: 'PR 合并完成并已清理分支', output: res.rawOutput };
+                }
+                default:
+                    throw new Error(`未知的 PR 操作: ${args.action}`);
+            }
+        },
+    });
+}

package/lib/tools/repo.d.ts

@@ -0,0 +1,2 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createRepoTool(executor: GhExecutor): any;

package/lib/tools/repo.js

@@ -0,0 +1,68 @@
+import { defineSafeTool } from './define.js';
+export function createRepoTool(executor) {
+    return defineSafeTool({
+        name: 'github_repo',
+        description: '查看 GitHub 仓库元数据与跨仓库检索代码、Issue。默认查询当前工作区关联的仓库。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['view', 'search_code', 'search_repos'],
+                    description: '仓库操作类型。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前仓库。',
+                },
+                query: {
+                    type: 'string',
+                    description: '检索关键词（search_code 或 search_repos 时使用）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回条数，默认 10。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const limitStr = String(args.limit || 10);
+            switch (args.action) {
+                case 'view': {
+                    const repoArgs = args.repo ? [args.repo] : [];
+                    const res = await executor.run(['repo', 'view', ...repoArgs, '--json', 'nameWithOwner,description,defaultBranchRef,isPrivate,stargazerCount,forkCount,url'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'search_code': {
+                    if (!args.query)
+                        throw new Error('search_code 必须提供 query');
+                    const repoArgs = args.repo ? ['--repo', args.repo] : [];
+                    const res = await executor.run(['search', 'code', args.query, ...repoArgs, '--json', 'path,repository,textMatches', '-L', limitStr], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'search_repos': {
+                    if (!args.query)
+                        throw new Error('search_repos 必须提供 query');
+                    const res = await executor.run(['search', 'repos', args.query, '--json', 'fullName,description,stargazersCount,updatedAt', '-L', limitStr], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                default:
+                    throw new Error(`未知的 Repo 操作: ${args.action}`);
+            }
+        },
+    });
+}

package/lib/tools/run.d.ts

@@ -0,0 +1,2 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createRunTool(executor: GhExecutor): any;

package/lib/tools/run.js

@@ -0,0 +1,87 @@
+import { defineSafeTool } from './define.js';
+export function createRunTool(executor) {
+    return defineSafeTool({
+        name: 'github_run',
+        description: '排查和诊断 GitHub Actions 工作流构建状态。特别优化了获取失败步骤日志能力（log_failed），专供 Agent 快速定位 CI 报错。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'log_failed', 'rerun', 'cancel'],
+                    description: 'Actions 操作类型。',
+                },
+                run_id: {
+                    type: 'string',
+                    description: 'Workflow 运行 ID（view, log_failed, rerun, cancel 时使用）。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前仓库。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '列出 runs 的数量，默认 10。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const repoArgs = args.repo ? ['-R', args.repo] : [];
+            switch (args.action) {
+                case 'list': {
+                    const res = await executor.run(['run', 'list', ...repoArgs, '--json', 'databaseId,name,status,conclusion,event,headBranch,createdAt', '-L', String(args.limit || 10)], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'view': {
+                    if (!args.run_id)
+                        throw new Error('view 操作必须提供 run_id');
+                    const res = await executor.run(['run', 'view', String(args.run_id), ...repoArgs, '--json', 'databaseId,name,status,conclusion,jobs,url'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.data || res.rawOutput;
+                }
+                case 'log_failed': {
+                    if (!args.run_id)
+                        throw new Error('log_failed 操作必须提供 run_id');
+                    // gh 原生支持仅提取失败的日志！对 Agent 故障诊断价值极高
+                    const res = await executor.run(['run', 'view', String(args.run_id), ...repoArgs, '--log-failed'], {
+                        cwd,
+                        timeoutMs: 60_000,
+                        rawText: true,
+                    });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return res.rawOutput || '未找到失败步骤的日志';
+                }
+                case 'rerun': {
+                    if (!args.run_id)
+                        throw new Error('rerun 操作必须提供 run_id');
+                    const res = await executor.run(['run', 'rerun', String(args.run_id), ...repoArgs, '--failed'], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: '已成功重新触发失败任务', output: res.rawOutput };
+                }
+                case 'cancel': {
+                    if (!args.run_id)
+                        throw new Error('cancel 操作必须提供 run_id');
+                    const res = await executor.run(['run', 'cancel', String(args.run_id), ...repoArgs], { cwd });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: '已取消该工作流任务', output: res.rawOutput };
+                }
+                default:
+                    throw new Error(`未知的 Run 操作: ${args.action}`);
+            }
+        },
+    });
+}

package/lib/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * DSH GitHub 插件核心数据类型定义
+ */
+export interface PluginConfig {
+    /** GitHub CLI (gh) 可执行文件路径，默认 'gh' */
+    ghPath?: string;
+    /** 进程超时限制（毫秒），默认 30,000ms */
+    defaultTimeoutMs?: number;
+    /** 单次安全输出字符数上限（防止 Token 溢出），默认 24,000 */
+    maxOutputChars?: number;
+    /** Web API 概览数据缓存时长（毫秒），默认 15,000ms */
+    cacheTtlMs?: number;
+    /** 查询列表默认限制条数，默认 20 */
+    defaultListLimit?: number;
+}
+export interface GhExecutionOptions {
+    /** 命令执行的工作目录，优先使用当前 Agent 会话所在的 Workspace 物理路径 */
+    cwd?: string;
+    /** 进程超时限制（毫秒），默认 30,000ms */
+    timeoutMs?: number;
+    /** 附加环境变量 */
+    env?: NodeJS.ProcessEnv;
+    /** 是否强制以纯文本形式返回，不进行 JSON 尝试解析 */
+    rawText?: boolean;
+}
+export interface GhResult<T = unknown> {
+    ok: boolean;
+    data?: T;
+    rawOutput?: string;
+    error?: string;
+    /** 是否因超出安全阈值而被截断 */
+    truncated?: boolean;
+}
+export interface AuthStatus {
+    installed: boolean;
+    loggedIn: boolean;
+    platform?: string;
+    user?: string;
+    host?: string;
+    activeAccount?: boolean;
+    protocol?: string;
+    scopes?: string[];
+    raw?: string;
+}
+export interface RepoMetadata {
+    nameWithOwner: string;
+    name: string;
+    owner: string;
+    defaultBranch: string;
+    currentBranch?: string;
+    description?: string;
+    isPrivate?: boolean;
+    url?: string;
+}
+export interface PrItem {
+    number: number;
+    title: string;
+    state: 'OPEN' | 'CLOSED' | 'MERGED';
+    author: {
+        login: string;
+        avatarUrl?: string;
+    };
+    headRefName: string;
+    baseRefName: string;
+    isDraft: boolean;
+    mergeable?: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN';
+    reviewDecision?: 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED';
+    statusCheckRollup?: Array<{
+        name: string;
+        status: string;
+        conclusion: string;
+    }>;
+    url: string;
+    updatedAt: string;
+}
+export interface IssueItem {
+    number: number;
+    title: string;
+    state: 'OPEN' | 'CLOSED';
+    author: {
+        login: string;
+    };
+    labels: Array<{
+        name: string;
+        color: string;
+    }>;
+    assignees: Array<{
+        login: string;
+    }>;
+    url: string;
+    updatedAt: string;
+}
+export interface WorkflowRunItem {
+    databaseId: number;
+    name: string;
+    status: 'queued' | 'in_progress' | 'completed';
+    conclusion?: 'success' | 'failure' | 'cancelled' | 'skipped';
+    event: string;
+    headBranch: string;
+    url: string;
+    createdAt: string;
+}
+export interface GitHubOverviewData {
+    auth: AuthStatus;
+    repo?: RepoMetadata;
+    pullRequests: PrItem[];
+    issues: IssueItem[];
+    runs: WorkflowRunItem[];
+    lastUpdated: string;
+    error?: string;
+}
+export interface UserRepoItem {
+    name: string;
+    nameWithOwner: string;
+    description?: string;
+    defaultBranch: string;
+    isPrivate: boolean;
+    stargazerCount?: number;
+    updatedAt: string;
+    url: string;
+}
+export interface WorkspaceMatrixItem {
+    id: string;
+    title: string;
+    path: string;
+    hasGit: boolean;
+    repo?: RepoMetadata;
+    sessionCount: number;
+}
+export interface GlobalOverviewData {
+    auth: AuthStatus;
+    userRepos: UserRepoItem[];
+    workspaceMatrix: WorkspaceMatrixItem[];
+    myPrs: Array<{
+        number: number;
+        title: string;
+        repository: {
+            nameWithOwner: string;
+        };
+        url: string;
+        updatedAt: string;
+    }>;
+    myIssues: Array<{
+        number: number;
+        title: string;
+        repository: {
+            nameWithOwner: string;
+        };
+        url: string;
+        updatedAt: string;
+    }>;
+    lastUpdated: string;
+    error?: string;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'github/pr:create'(repo: string, pr: {
+            title: string;
+            url: string;
+        }): void;
+        'github/pr:merge'(repo: string, prNumber: number): void;
+        'github/issue:create'(repo: string, issue: {
+            title: string;
+            url: string;
+        }): void;
+    }
+}

package/lib/types.js

@@ -0,0 +1,4 @@
+/**
+ * DSH GitHub 插件核心数据类型定义
+ */
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "dsh-github-flow",
+  "version": "0.1.0",
+  "icon": "icon.svg",
+  "description": "GitHub Flow: Native GitHub CLI (gh) integration for DeepSeek Harness — Agent Tools, Slash Commands, and Web UI Workspace",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/build.mjs",
+    "prepare": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "entry": "./lib/client.js"
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "github",
+    "gh-cli",
+    "cordis"
+  ],
+  "author": "DSH Contributor",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2"
+  }
+}