dsh-github-flow 0.3.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/cache.d.ts

@@ -0,0 +1,64 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createCacheTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            cache_id: {
+                type: string;
+                description: string;
+            };
+            key: {
+                type: string;
+                description: string;
+            };
+            ref: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            sort: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            order: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            all: {
+                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>>;
+};

package/lib/tools/cache.js

@@ -0,0 +1,186 @@
+import { renderCacheMarkdown } 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 : '' };
+}
+export function createCacheTool(executor) {
+    return {
+        name: 'github_cache',
+        description: '管理 GitHub Actions 构建缓存 (Caches)：查看缓存列表与占用容量、按 ID 或 Key 删除指定缓存、以及全量清空仓库缓存。全量清空不可逆，需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'delete'],
+                    description: 'Cache 操作类型。list 查看缓存列表与体积、delete 删除缓存。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                cache_id: {
+                    type: 'string',
+                    description: '缓存数字 ID（delete 动作指定单条缓存删除时使用）。',
+                },
+                key: {
+                    type: 'string',
+                    description: '缓存 Key 键名前缀或完整键名（list 动作过滤检索，或 delete 动作按键删除时使用）。',
+                },
+                ref: {
+                    type: 'string',
+                    description: '分支或 PR Git Ref（如 "refs/heads/main" 或 "refs/pull/42/merge"，用于过滤或定向删除）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回缓存数量上限（list 动作使用，默认 30）。',
+                },
+                sort: {
+                    type: 'string',
+                    enum: ['created_at', 'last_accessed_at', 'size_in_bytes'],
+                    description: '排序字段（list 动作使用，默认 last_accessed_at）。',
+                },
+                order: {
+                    type: 'string',
+                    enum: ['asc', 'desc'],
+                    description: '排序方向（list 动作使用，默认 desc）。',
+                },
+                all: {
+                    type: 'boolean',
+                    description: '是否清空仓库全部缓存（delete 动作使用，高危操作，必需配合 confirm: true）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（delete 当 all: true 时必需）。未传 true 时输出影响评估报告并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderCacheMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            let repoTarget = args.repo;
+            if (!repoTarget) {
+                const meta = await executor.getRepoMetadata(cwd, sessionId);
+                if (meta?.nameWithOwner) {
+                    repoTarget = meta.nameWithOwner;
+                }
+            }
+            if (!repoTarget) {
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]（例如: "ItQianChen/dsh-github-flow"），或在当前工作区目录下关联 Git 远程仓库。');
+            }
+            const repoArgs = ['-R', repoTarget];
+            const runOpts = { cwd, sessionId };
+            switch (args.action) {
+                case 'list': {
+                    const listCmd = [
+                        'cache',
+                        'list',
+                        ...repoArgs,
+                        '--json',
+                        'createdAt,id,key,lastAccessedAt,ref,sizeInBytes,version',
+                    ];
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 30;
+                    listCmd.push('-L', String(limit));
+                    if (args.key) {
+                        listCmd.push('-k', String(args.key));
+                    }
+                    if (args.ref) {
+                        listCmd.push('-r', String(args.ref));
+                    }
+                    if (args.sort) {
+                        listCmd.push('--sort', args.sort);
+                    }
+                    if (args.order) {
+                        listCmd.push('--order', args.order);
+                    }
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    let rawData = res.data;
+                    if (!rawData && typeof res.rawOutput === 'string') {
+                        try {
+                            rawData = JSON.parse(res.rawOutput);
+                        }
+                        catch {
+                            rawData = [];
+                        }
+                    }
+                    return normalizeOutput(rawData || []);
+                }
+                case 'delete': {
+                    // 1. 全量清空分支
+                    if (args.all === true) {
+                        if (args.confirm !== true) {
+                            return {
+                                status: 'AWAITING_CONFIRMATION',
+                                action: 'delete',
+                                all: true,
+                                repo: repoTarget,
+                                warning: `⚠️ 高危破坏性操作：即将清空仓库 ${repoTarget} 的所有 GitHub Actions 构建缓存`,
+                                impact: `清空缓存不可逆，会导致后续流水线构建无法复用依赖与构建产物，显著增加 CI 运行耗时。`,
+                                requiredAction: `如确认彻底清空，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_cache(action: 'delete', all: true, confirm: true)\``,
+                            };
+                        }
+                        const delCmd = ['cache', 'delete', '--all', '--succeed-on-no-caches', ...repoArgs];
+                        if (args.ref) {
+                            delCmd.push('-r', String(args.ref));
+                        }
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            all: true,
+                            message: `🗑️ 成功清空仓库 ${repoTarget} 的 Actions 构建缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    // 2. 按 cache_id 删除
+                    if (args.cache_id !== undefined && args.cache_id !== null && String(args.cache_id).trim() !== '') {
+                        const delCmd = ['cache', 'delete', String(args.cache_id), ...repoArgs];
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            cache_id: String(args.cache_id),
+                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 ID 为 "${args.cache_id}" 的 Actions 缓存`,
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    // 3. 按 key 删除
+                    if (args.key !== undefined && args.key !== null && String(args.key).trim() !== '') {
+                        const delCmd = ['cache', 'delete', String(args.key), ...repoArgs];
+                        if (args.ref) {
+                            delCmd.push('-r', String(args.ref));
+                        }
+                        const res = await executor.run(delCmd, runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return {
+                            success: true,
+                            key: String(args.key),
+                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 Key 为 "${args.key}" 的 Actions 缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
+                            detail: res.rawOutput || '',
+                        };
+                    }
+                    throw new Error('删除缓存时必须指定 `cache_id`、`key` 或 `all: true`（全量删除需配合 confirm: true）。');
+                }
+                default:
+                    throw new Error(`不支持的 cache 操作: "${args.action}"。可选值: list, delete。`);
+            }
+        },
+    };
+}

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