dsh-github-flow 0.4.0 → 0.5.0

package/lib/telemetry.js

@@ -0,0 +1,161 @@
+/**
+ * DSH GitHub Flow - 运行时遥测审计与降级率收集器
+ *
+ * 遵循 /dsh-plugin-dev-skill 规范，利用 Cordis 的 tools/result 事件总线
+ * 建立内存中固定容量的轻量无锁环形队列，实现零外部数据库依赖、常驻内存严格 <200KB
+ * 的工业级运行时可观测性，量化分析 18 大工具矩阵的 API 降级率与健康度指标。
+ */
+/**
+ * 内存固定容量环形队列（无锁、确定性内存上限）
+ */
+export class TelemetryRingBuffer {
+    buffer = [];
+    capacity;
+    constructor(capacity = 200) {
+        this.capacity = Math.max(1, capacity);
+    }
+    push(record) {
+        if (this.buffer.length >= this.capacity) {
+            this.buffer.shift(); // 先进先出丢弃最旧的一条
+        }
+        this.buffer.push(record);
+    }
+    getAll() {
+        return [...this.buffer];
+    }
+    size() {
+        return this.buffer.length;
+    }
+    clear() {
+        this.buffer = [];
+    }
+}
+/**
+ * 遥测收集与健康分析引擎
+ */
+export class TelemetryCollector {
+    ringBuffer;
+    callCounter = 0;
+    constructor(capacity = 200) {
+        this.ringBuffer = new TelemetryRingBuffer(capacity);
+    }
+    /**
+     * 记录一次工具调用结果（Fail-Open 保护，绝不阻滞主流程）
+     */
+    recordCall(name, args, result, durationMs) {
+        try {
+            if (!name || typeof name !== 'string')
+                return;
+            this.callCounter++;
+            const action = typeof args?.action === 'string' ? args.action : undefined;
+            const isScopeBlocked = result?.status === 'SCOPE_REQUIRED';
+            const isConfirmBlocked = result?.status === 'AWAITING_CONFIRMATION';
+            const isBlocked = isScopeBlocked || isConfirmBlocked;
+            const isDegraded = result?.degraded === true || result?.data?.degraded === true;
+            const isFailed = !isBlocked && (result?.ok === false || result?.success === false || !!result?.error);
+            const record = {
+                id: `t_${Date.now()}_${this.callCounter}`,
+                timestamp: Date.now(),
+                toolName: name,
+                action,
+                durationMs: typeof durationMs === 'number' && durationMs >= 0 ? durationMs : undefined,
+                success: !isFailed && !isBlocked,
+                degraded: isDegraded,
+                scopeBlocked: isScopeBlocked,
+                confirmBlocked: isConfirmBlocked,
+                errorType: isFailed ? String(result?.error || 'UNKNOWN_ERROR').slice(0, 50) : undefined,
+            };
+            this.ringBuffer.push(record);
+        }
+        catch {
+            // 遥测打点非阻塞隔离：严禁将任何收集器内部异常外溢给调用方
+        }
+    }
+    /**
+     * 生成工具链健康度与降级率统计大盘
+     */
+    getSummary() {
+        const records = this.ringBuffer.getAll();
+        const totalCalls = records.length;
+        let successCount = 0;
+        let failureCount = 0;
+        let degradedCount = 0;
+        let scopeBlockedCount = 0;
+        let confirmBlockedCount = 0;
+        const toolStats = {};
+        for (const r of records) {
+            if (!toolStats[r.toolName]) {
+                toolStats[r.toolName] = { total: 0, success: 0, degraded: 0, failed: 0, blocked: 0 };
+            }
+            const stat = toolStats[r.toolName];
+            stat.total++;
+            if (r.degraded) {
+                degradedCount++;
+                stat.degraded++;
+            }
+            if (r.scopeBlocked) {
+                scopeBlockedCount++;
+                stat.blocked++;
+            }
+            if (r.confirmBlocked) {
+                confirmBlockedCount++;
+                stat.blocked++;
+            }
+            if (r.success) {
+                successCount++;
+                stat.success++;
+            }
+            else if (!r.scopeBlocked && !r.confirmBlocked) {
+                failureCount++;
+                stat.failed++;
+            }
+        }
+        const degradationRate = totalCalls > 0 ? Number(((degradedCount / totalCalls) * 100).toFixed(1)) : 0;
+        const failureRate = totalCalls > 0 ? (failureCount / totalCalls) * 100 : 0;
+        // 健康分计算算法：基准 100 分，按降级率（权重 0.4）与失败率（权重 0.5）综合惩罚
+        let healthScore = 100;
+        if (totalCalls > 0) {
+            const penalty = degradationRate * 0.4 + failureRate * 0.5;
+            healthScore = Math.max(0, Math.round(100 - penalty));
+        }
+        let statusLevel = 'EXCELLENT';
+        if (healthScore < 70) {
+            statusLevel = 'NEEDS_ATTENTION';
+        }
+        else if (healthScore < 90) {
+            statusLevel = 'GOOD';
+        }
+        // 智能自愈建议推导
+        const recommendations = [];
+        if (toolStats['github_repo'] && toolStats['github_repo'].degraded > 0) {
+            recommendations.push('发现 github_repo 文件读取触发了 API 降级链路，建议将 GitHub CLI 升级至 2.95.0+ 以启用原生免克隆极速读取。');
+        }
+        if (scopeBlockedCount > 0) {
+            recommendations.push('发现因缺少 OAuth Scope 导致调用拦截，请在终端执行相应的 `gh auth refresh -s <scope>` 补全授权。');
+        }
+        if (degradationRate > 20) {
+            recommendations.push('当前工具链整体 API 降级率较高，可能当前宿主 CLI 版本过低，建议运行 `/gh upgrade` 检查升级。');
+        }
+        if (recommendations.length === 0) {
+            recommendations.push('工具链运行状态极佳，所有调用均走原生高速通道，无降级与权限阻断。');
+        }
+        return {
+            totalCalls,
+            successCount,
+            failureCount,
+            degradedCount,
+            degradationRate,
+            scopeBlockedCount,
+            confirmBlockedCount,
+            healthScore,
+            statusLevel,
+            toolStats,
+            recommendations,
+        };
+    }
+    clear() {
+        this.ringBuffer.clear();
+    }
+}
+/** 全局单例收集器实例 */
+export const defaultTelemetryCollector = new TelemetryCollector(200);

package/lib/tools/agent-task.d.ts

@@ -0,0 +1,54 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createAgentTaskTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            task_id: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                type: string;
+                description: string;
+            };
+            base_branch: {
+                type: string;
+                description: string;
+            };
+            custom_agent: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            log: {
+                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<any>;
+};

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>>;
+};