dsh-github-flow 0.4.0 → 0.6.0

package/lib/tools/agent-task.js

@@ -0,0 +1,135 @@
+import { renderAgentTaskMarkdown } from '../renderers/markdown.js';
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+const AGENT_TASK_JSON_FIELDS = 'completedAt,createdAt,id,name,pullRequestNumber,pullRequestState,pullRequestTitle,pullRequestUrl,repository,state,updatedAt,user';
+export function createAgentTaskTool(executor) {
+    return {
+        name: 'github_agent_task',
+        description: '管理 GitHub Copilot Coding Agent 云端智能体任务会话：查看已分派任务列表、检视任务状态与会话日志、向云端智能体发起新编码与重构任务。基于 gh CLI preview 特性。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'create'],
+                    description: 'Agent Task 操作类型。list 查看任务列表、view 检视任务详情与日志、create 新建智能体任务。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                task_id: {
+                    type: 'string',
+                    description: '任务标识（view 动作必需，支持 Session ID、PR 编号或任务 URL）。',
+                },
+                prompt: {
+                    type: 'string',
+                    description: '任务描述正文或编码指令（create 动作必需，如 "为用户模块增加单元测试"）。',
+                },
+                base_branch: {
+                    type: 'string',
+                    description: 'PR 基准分支（create 动作可选，映射 -b/--base，缺省为主干默认分支）。',
+                },
+                custom_agent: {
+                    type: 'string',
+                    description: '自定义 Agent 规范名称（create 动作可选，映射 -a/--custom-agent，对应 .github/agents/ 规范）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回任务数量上限（list 动作使用，默认 30）。',
+                },
+                log: {
+                    type: 'boolean',
+                    description: '是否一并拉取任务会话执行日志（view 动作可选，映射 --log）。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderAgentTaskMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const repoArgs = args.repo ? ['-R', args.repo] : [];
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    // 注意：gh agent-task list 属于账号级任务列表命令，上游 gh CLI 官方不接受 -R/--repo 标志
+                    const listCmd = [
+                        'agent-task', 'list',
+                        '-L', String(limit),
+                        '--json', AGENT_TASK_JSON_FIELDS,
+                    ];
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'view': {
+                    // 防线：task_id 必须显式提供，防止 CLI 打开交互式选择器导致无头进程挂死
+                    if (!args.task_id || typeof args.task_id !== 'string' || !args.task_id.trim()) {
+                        throw new Error('view 操作必须提供 task_id（支持 Session ID、PR 编号或任务 URL），以防止交互式挂起');
+                    }
+                    const cleanId = args.task_id.trim();
+                    const viewCmd = [
+                        'agent-task', 'view', cleanId,
+                        '--json', AGENT_TASK_JSON_FIELDS,
+                        ...repoArgs,
+                    ];
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    let taskData = res.data;
+                    if (!taskData && res.rawOutput) {
+                        try {
+                            taskData = JSON.parse(res.rawOutput);
+                        }
+                        catch {
+                            taskData = { id: cleanId, result: res.rawOutput };
+                        }
+                    }
+                    // 若调用方需要日志，额外抓取 session log 并挂载
+                    if (args.log === true && taskData && typeof taskData === 'object') {
+                        const logCmd = ['agent-task', 'view', cleanId, '--log', ...repoArgs];
+                        const logRes = await executor.run(logCmd, { ...runOpts, rawText: true, timeoutMs: 45_000 });
+                        if (logRes.ok && logRes.rawOutput) {
+                            taskData.logs = logRes.rawOutput;
+                        }
+                    }
+                    return taskData || { id: cleanId };
+                }
+                case 'create': {
+                    if (!args.prompt || typeof args.prompt !== 'string' || !args.prompt.trim()) {
+                        throw new Error('create 操作必须提供 prompt（任务描述正文或编码指令）');
+                    }
+                    const createCmd = ['agent-task', 'create', args.prompt.trim(), ...repoArgs];
+                    if (args.base_branch)
+                        createCmd.push('-b', args.base_branch.trim());
+                    if (args.custom_agent)
+                        createCmd.push('-a', args.custom_agent.trim());
+                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        message: '智能体任务已成功创建并派发',
+                        output: res.rawOutput || 'Agent task dispatched',
+                    };
+                }
+                default:
+                    throw new Error(`未知的 Agent Task 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/tools/codespace.d.ts

@@ -0,0 +1,51 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createCodespaceTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            codespace: {
+                type: string;
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            org: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any> | {
+        status: string;
+        scope: string;
+        command: string;
+        tool: string;
+    }>;
+};

package/lib/tools/codespace.js

@@ -0,0 +1,154 @@
+import { renderCodespaceMarkdown } from '../renderers/markdown.js';
+import { checkScopeRequired } from './project.js';
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+const CODESPACE_LIST_FIELDS = 'name,displayName,repository,owner,state,gitStatus,lastUsedAt,createdAt,machineName';
+const CODESPACE_VIEW_FIELDS = 'name,displayName,repository,owner,state,gitStatus,lastUsedAt,createdAt,machineName,devcontainerPath,recentFolders,idleTimeoutMinutes';
+export function createCodespaceTool(executor) {
+    return {
+        name: 'github_codespace',
+        description: '管理 GitHub Codespaces 云端远程开发环境：查阅实例列表与运行状态、检视实例配置详情、停止运行中的环境防计费、安全销毁实例。未授权时提供平台感知自愈命令。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'stop', 'delete'],
+                    description: 'Codespace 操作类型。list 查看环境列表、view 检视详情、stop 停止运行（防持续计费）、delete 销毁实例（需 confirm）。',
+                },
+                codespace: {
+                    type: 'string',
+                    description: 'Codespace 实例名称（view, stop, delete 动作必需，如 "fuzzy-spoon-69vj"；防交互式挂起）。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '按目标仓库筛选 [owner/repo]（list 动作可选）。',
+                },
+                org: {
+                    type: 'string',
+                    description: '组织管理员按组织筛选（list, stop, delete 动作可选）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回数量上限（list 动作使用，默认 30）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '危险操作确认标记（delete 动作必需）。销毁云端环境不可逆，未确认时输出影响评估并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderCodespaceMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    const listCmd = [
+                        'codespace', 'list',
+                        '-L', String(limit),
+                        '--json', CODESPACE_LIST_FIELDS,
+                    ];
+                    if (args.repo)
+                        listCmd.push('-R', String(args.repo).trim());
+                    if (args.org)
+                        listCmd.push('-o', String(args.org).trim());
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'codespace', 'gh auth refresh -h github.com -s codespace', 'github_codespace');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'view': {
+                    if (!args.codespace || typeof args.codespace !== 'string' || !args.codespace.trim()) {
+                        throw new Error('view 操作必须提供 codespace 名称，以防止 CLI 打开交互式选择器导致挂起');
+                    }
+                    const cleanName = args.codespace.trim();
+                    const viewCmd = [
+                        'codespace', 'view',
+                        '-c', cleanName,
+                        '--json', CODESPACE_VIEW_FIELDS,
+                    ];
+                    if (args.repo)
+                        viewCmd.push('-R', String(args.repo).trim());
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'codespace', 'gh auth refresh -h github.com -s codespace', 'github_codespace');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'stop': {
+                    if (!args.codespace || typeof args.codespace !== 'string' || !args.codespace.trim()) {
+                        throw new Error('stop 操作必须提供 codespace 名称，以防止 CLI 进入交互式挂起');
+                    }
+                    const cleanName = args.codespace.trim();
+                    const stopCmd = ['codespace', 'stop', '-c', cleanName];
+                    if (args.org)
+                        stopCmd.push('-o', String(args.org).trim());
+                    const res = await executor.run(stopCmd, { ...runOpts, rawText: true, timeoutMs: 45_000 });
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'codespace', 'gh auth refresh -h github.com -s codespace', 'github_codespace');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `云端开发环境「${cleanName}」已成功发送停止指令（已避免继续占用算力计费）`,
+                        output: res.rawOutput || 'Stopped',
+                    };
+                }
+                case 'delete': {
+                    if (!args.codespace || typeof args.codespace !== 'string' || !args.codespace.trim()) {
+                        throw new Error('delete 操作必须提供 codespace 名称');
+                    }
+                    const cleanName = args.codespace.trim();
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 销毁确认拦截：你即将永久删除云端开发环境「${cleanName}」。`,
+                            impact: '物理销毁 Codespace 将永久释放云端计算资源，环境中任何未提交并推送到远端 Git 的临时修改都将无法找回。',
+                            requiredAction: '如确认销毁该实例，请核对环境名称并在参数中附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const deleteCmd = ['codespace', 'delete', '-c', cleanName, '-f'];
+                    if (args.org)
+                        deleteCmd.push('-o', String(args.org).trim());
+                    const res = await executor.run(deleteCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'codespace', 'gh auth refresh -h github.com -s codespace', 'github_codespace');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `云端开发环境「${cleanName}」已成功销毁释放`,
+                        output: res.rawOutput || 'Deleted',
+                    };
+                }
+                default:
+                    throw new Error(`未知的 Codespace 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/tools/discussion.d.ts

@@ -0,0 +1,70 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createDiscussionTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            discussion_number: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            body: {
+                type: string;
+                description: string;
+            };
+            category: {
+                type: string;
+                description: string;
+            };
+            state: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            labels: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            search: {
+                type: string;
+                description: string;
+            };
+            comments: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any>>;
+};

package/lib/tools/discussion.js

@@ -0,0 +1,195 @@
+import { renderDiscussionMarkdown } from '../renderers/markdown.js';
+function normalizeOutput(data) {
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return { items: data, count: data.length };
+    }
+    return { result: data !== undefined && data !== null ? data : '' };
+}
+const DISCUSSION_LIST_FIELDS = 'number,title,body,category,author,closed,createdAt,updatedAt,url,labels,answered,stateReason';
+const DISCUSSION_VIEW_FIELDS = 'number,title,body,category,author,state,createdAt,updatedAt,url,labels,answered,comments';
+export function createDiscussionTool(executor) {
+    return {
+        name: 'github_discussion',
+        description: '管理 GitHub Discussions 讨论区：浏览社区讨论、检视讨论详情与回复楼层、发起新讨论议题、编辑现有讨论以及追加评论回复。基于 gh CLI preview 特性。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'create', 'edit', 'comment'],
+                    description: 'Discussion 操作类型。list 查阅讨论列表、view 查看正文与评论、create 发起新讨论、edit 修改讨论、comment 发表评论。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                discussion_number: {
+                    type: 'number',
+                    description: '讨论编号（view, edit, comment 动作必需，如 123）。',
+                },
+                title: {
+                    type: 'string',
+                    description: '讨论标题（create 动作必需，edit 动作修改标题时可选）。',
+                },
+                body: {
+                    type: 'string',
+                    description: '讨论正文或评论正文（create, comment 必需，edit 动作修改正文时可选）。',
+                },
+                category: {
+                    type: 'string',
+                    description: '讨论分类名称（create 动作必需，list 动作按分类筛选使用，如 "General"、"Q&A"、"Ideas"）。',
+                },
+                state: {
+                    type: 'string',
+                    enum: ['open', 'closed', 'all'],
+                    description: '讨论状态过滤（list 动作使用，默认 open）。',
+                },
+                labels: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '按标签筛选（list 动作使用）。',
+                },
+                search: {
+                    type: 'string',
+                    description: '搜索过滤关键词（list 动作使用，映射 -S/--search）。',
+                },
+                comments: {
+                    type: 'boolean',
+                    description: '是否一并拉取评论列表（view 动作使用，默认 true）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回讨论数量上限（list 动作使用，默认 30）。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderDiscussionMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const repoArgs = args.repo ? ['-R', args.repo] : [];
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    const listCmd = [
+                        'discussion', 'list',
+                        '-L', String(limit),
+                        '--json', DISCUSSION_LIST_FIELDS,
+                        ...repoArgs,
+                    ];
+                    if (args.category)
+                        listCmd.push('-c', String(args.category).trim());
+                    if (args.state)
+                        listCmd.push('-s', args.state);
+                    if (args.search)
+                        listCmd.push('-S', String(args.search).trim());
+                    if (Array.isArray(args.labels) && args.labels.length > 0) {
+                        args.labels.forEach((l) => {
+                            if (l)
+                                listCmd.push('-l', String(l).trim());
+                        });
+                    }
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'view': {
+                    if (!args.discussion_number || typeof args.discussion_number !== 'number') {
+                        throw new Error('view 操作必须提供 discussion_number（讨论数字编号），以防止进入交互式挂起');
+                    }
+                    const numStr = String(args.discussion_number);
+                    const viewCmd = [
+                        'discussion', 'view', numStr,
+                        '--json', DISCUSSION_VIEW_FIELDS,
+                        ...repoArgs,
+                    ];
+                    if (args.comments !== false) {
+                        viewCmd.push('-c');
+                    }
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'create': {
+                    if (!args.title || typeof args.title !== 'string' || !args.title.trim()) {
+                        throw new Error('create 操作必须提供 title（讨论标题）');
+                    }
+                    if (!args.body || typeof args.body !== 'string' || !args.body.trim()) {
+                        throw new Error('create 操作必须提供 body（讨论正文）');
+                    }
+                    if (!args.category || typeof args.category !== 'string' || !args.category.trim()) {
+                        throw new Error('create 操作必须提供 category（讨论分类，例如 "General"、"Q&A"、"Ideas"）');
+                    }
+                    const createCmd = [
+                        'discussion', 'create',
+                        '-t', args.title.trim(),
+                        '-b', args.body.trim(),
+                        '-c', args.category.trim(),
+                        ...repoArgs,
+                    ];
+                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        message: '讨论已成功发起',
+                        url: res.rawOutput ? res.rawOutput.trim() : undefined,
+                    };
+                }
+                case 'edit': {
+                    if (!args.discussion_number || typeof args.discussion_number !== 'number') {
+                        throw new Error('edit 操作必须提供 discussion_number（讨论数字编号）');
+                    }
+                    if (!args.title && !args.body) {
+                        throw new Error('edit 操作至少需提供 title 或 body 中的一项进行修改');
+                    }
+                    const editCmd = ['discussion', 'edit', String(args.discussion_number), ...repoArgs];
+                    if (args.title)
+                        editCmd.push('-t', String(args.title).trim());
+                    if (args.body)
+                        editCmd.push('-b', String(args.body).trim());
+                    const res = await executor.run(editCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        message: `讨论 #${args.discussion_number} 已更新成功`,
+                        output: res.rawOutput || 'Updated',
+                    };
+                }
+                case 'comment': {
+                    if (!args.discussion_number || typeof args.discussion_number !== 'number') {
+                        throw new Error('comment 操作必须提供 discussion_number（讨论数字编号）');
+                    }
+                    if (!args.body || typeof args.body !== 'string' || !args.body.trim()) {
+                        throw new Error('comment 操作必须提供 body（评论正文）');
+                    }
+                    const commentCmd = [
+                        'discussion', 'comment', String(args.discussion_number),
+                        '-b', args.body.trim(),
+                        ...repoArgs,
+                    ];
+                    const res = await executor.run(commentCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        message: `已向讨论 #${args.discussion_number} 成功发表评论`,
+                        url: res.rawOutput ? res.rawOutput.trim() : undefined,
+                    };
+                }
+                default:
+                    throw new Error(`未知的 Discussion 操作: ${args.action}`);
+            }
+        },
+    };
+}