dsh-github-flow 0.4.0 → 0.6.0

package/lib/renderers/skill.js

@@ -14,6 +14,11 @@ export function renderSkillMarkdown(args, value) {
     }
     if (typeof value.result === 'string')
         return value.result;
+    // 6.0 特化 action 处理（update）
+    if (args?.action === 'update' || value?.action === 'update') {
+        const extra = value.output || value.detail;
+        return `### 🔄 ${value.message || 'Agent Skills 更新结果'}\n` + (extra ? `\`\`\`text\n${String(extra).trim()}\n\`\`\`` : '');
+    }
     if (typeof value.message === 'string' && !value.items) {
         const extra = value.detail || value.output;
         return `**${value.message}**` + (extra ? `\n\`\`\`\n${extra}\n\`\`\`` : '');
@@ -56,6 +61,181 @@ export function renderSkillMarkdown(args, value) {
             ...rows,
         ].join('\n');
     }
+    // 6.3 Skill 校验与发布报告
+    if (args?.action === 'publish' || value?.mode === 'dry-run' || value?.mode === 'fix' || value?.mode === 'publish') {
+        return renderSkillPublishMarkdown(value);
+    }
     // 兜底降级
     return JSON.stringify(value, null, 2);
 }
+/**
+ * 解析 gh skill publish 命令输出的 TSV 诊断行与状态汇总
+ *
+ * 核心设计理由与约束：
+ * 1. gh skill publish 命令无论成功还是失败，均采用制表符 `\t` 分隔的 TSV 纯文本行输出；
+ * 2. 诊断行格式：`error\t<skill>\t<msg>`、`warning\t<skill>\t<msg>`、`fixed\t<skill>\t<msg>` 或 `warning\t\t<repo_rule>`；
+ * 3. 校验失败时 exitCode 为 1，但其 stdout 中携带精准的错误项列表，需提取后结构化呈现，绝不能当作盲目异常吞没；
+ * 4. 若未匹配到有效技能或遇到无技能目录，从 stderr 提取根因提示。
+ */
+export function parseSkillPublishOutput(rawStdout, rawStderr, exitOk, mode, directory, tag) {
+    const items = [];
+    const repoWarnings = [];
+    let summary = '';
+    const combined = `${rawStdout || ''}\n${rawStderr || ''}`;
+    const lines = combined.split(/\r?\n/).map(l => l.trimEnd()).filter(Boolean);
+    for (const line of lines) {
+        // 匹配 TSV 诊断行：error/warning/fixed + \t + skillName + \t + message
+        const tsvMatch = line.match(/^(error|warning|fixed)\t([^\t]*)\t(.*)$/i);
+        if (tsvMatch) {
+            const type = tsvMatch[1].toLowerCase();
+            const skillName = tsvMatch[2].trim();
+            const message = tsvMatch[3].trim();
+            if (!skillName) {
+                // 技能名为空通常是仓库级规则警告（如 ruleset 缺少 tag 保护）
+                repoWarnings.push(message);
+            }
+            else {
+                items.push({ type, skillName, message });
+            }
+            continue;
+        }
+        // 汇总与特征行识别
+        if (/validation failed with \d+ error\(s\)/i.test(line)) {
+            summary = line.trim();
+        }
+        else if (/Dry run complete/i.test(line)) {
+            if (!summary)
+                summary = line.trim();
+        }
+        else if (/Fixed \d+ file\(s\)/i.test(line)) {
+            summary = line.trim();
+        }
+        else if (/no skills found in/i.test(line)) {
+            summary = line.trim();
+        }
+        else if (/Released/i.test(line) && mode === 'publish') {
+            if (!summary)
+                summary = line.trim();
+        }
+    }
+    // 判定最终业务成功态：
+    // 1. 若 items 中存在任一 error，则判定为失败；
+    // 2. 若 exitOk 为 false，即使没有 TSV 行也判定为失败；
+    // 3. dry-run 模式下无 error 且正常跑完判定为成功；
+    // 4. 若没有找到 skill（summary 包含 no skills found），视作失败并在 items 中追加说明项。
+    const hasErrors = items.some(i => i.type === 'error');
+    const noSkillsFound = summary.includes('no skills found in');
+    let success = exitOk && !hasErrors && !noSkillsFound;
+    if (noSkillsFound && items.length === 0) {
+        items.push({
+            type: 'error',
+            skillName: '-',
+            message: summary || '在目标目录下未检索到符合规范的 Agent Skill（需满足 skills/*/SKILL.md 等路径约束）',
+        });
+        success = false;
+    }
+    else if (!exitOk && items.length === 0 && rawStderr) {
+        // 其它非零退出且无 TSV 诊断行的情况，将 stderr 作为通用错误提示
+        items.push({
+            type: 'error',
+            skillName: '-',
+            message: rawStderr.trim(),
+        });
+        success = false;
+    }
+    return {
+        mode,
+        success,
+        directory,
+        items,
+        repoWarnings,
+        summary,
+        tag,
+        rawText: rawStdout.trim() || rawStderr.trim(),
+    };
+}
+/**
+ * Skill Publish 结构化 Markdown 渲染器
+ * 将体检报告、自动修复明细与正式发布结果转化为紧凑、清晰的表格与指引
+ */
+export function renderSkillPublishMarkdown(report) {
+    if (!report)
+        return '无返回内容';
+    if (report.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${report.warning || '⚠️ 操作确认拦截'}`,
+            `> - **影响评估**: ${report.impact || ''}`,
+            `> - **确认指引**: ${report.requiredAction || ''}`,
+        ].join('\n');
+    }
+    const sections = [];
+    const dirHint = report.directory ? ` (目录: \`${report.directory}\`)` : '';
+    if (report.mode === 'dry-run') {
+        const errorCount = report.items.filter(i => i.type === 'error').length;
+        const warningCount = report.items.filter(i => i.type === 'warning').length;
+        if (report.success && errorCount === 0) {
+            sections.push(`### ✅ Agent Skills 合规校验通过！${dirHint}\n`);
+            sections.push('受检 Skill 均符合 agentskills.io 规范（命名规范、目录匹配、必需 frontmatter 字段均通过）。');
+            if (warningCount > 0) {
+                sections.push(`\n**建议优化项 (${warningCount} 项):**`);
+            }
+        }
+        else {
+            sections.push(`### ⚠️ Agent Skills 校验发现问题 (${errorCount} 项错误${warningCount > 0 ? `，${warningCount} 项警告` : ''})${dirHint}\n`);
+        }
+        if (report.items.length > 0) {
+            const rows = report.items.map(item => {
+                let badge = 'ℹ️ 提示';
+                if (item.type === 'error')
+                    badge = '❌ 错误';
+                else if (item.type === 'warning')
+                    badge = '⚠️ 建议';
+                else if (item.type === 'fixed')
+                    badge = '🛠️ 已修复';
+                return `| ${badge} | \`${sanitizeCell(item.skillName, 30)}\` | ${sanitizeCell(item.message, 80)} |`;
+            });
+            sections.push('| 级别 | Skill 名称 | 问题详情与指引 |\n| :--- | :--- | :--- |\n' + rows.join('\n'));
+        }
+        if (report.repoWarnings && report.repoWarnings.length > 0) {
+            sections.push('\n**仓库策略提醒:**\n' + report.repoWarnings.map(w => `- 💡 ${w}`).join('\n'));
+        }
+        if (report.success && errorCount === 0) {
+            sections.push('\n> 💡 **正式发版指引**: 若需创建 GitHub Release 正式发布技能，请指定版本 Tag 并附带 `confirm: true`：\n> `github_skill(action: "publish", tag: "v1.0.0", dry_run: false, confirm: true)`');
+        }
+        else {
+            sections.push('\n> 🔍 **修复提示**: 若存在安装元数据残留，可先调用 `github_skill(action: "publish", fix: true)` 自动剥离清洗。');
+        }
+    }
+    else if (report.mode === 'fix') {
+        const fixedItems = report.items.filter(i => i.type === 'fixed');
+        sections.push(`### 🛠️ Agent Skills 元数据自动修复${report.success ? '完成' : '结果'}${dirHint}\n`);
+        if (fixedItems.length > 0) {
+            sections.push(`已自动清洗 **${fixedItems.length}** 处技能文件中的安装残留元数据（如 \`metadata.github-*\`）：\n`);
+            const rows = fixedItems.map(item => `| \`${sanitizeCell(item.skillName, 30)}\` | ${sanitizeCell(item.message, 80)} |`);
+            sections.push('| Skill 名称 | 修复操作 |\n| :--- | :--- |\n' + rows.join('\n'));
+            sections.push('\n> 📌 **后续步骤**: 请使用 `git diff` 审查本地文件变更，提交 Git 后再重新运行合规体检或发布。');
+        }
+        else {
+            sections.push(report.summary || '未检测到需要修复的元数据残留。');
+        }
+    }
+    else if (report.mode === 'publish') {
+        if (report.success) {
+            sections.push(`### 🚀 Agent Skill 发布成功！${dirHint}\n`);
+            sections.push(`- **版本 Tag**: \`${report.tag || '-'}\``);
+            sections.push('- **发布状态**: 已自动附加 `agent-skills` 仓库 Topic，并创建了关联 GitHub Release。');
+            if (report.summary)
+                sections.push(`\n${report.summary}`);
+        }
+        else {
+            sections.push(`### ❌ Agent Skill 发布失败${dirHint}\n`);
+            if (report.summary)
+                sections.push(`- **原因**: ${report.summary}`);
+            if (report.items.length > 0) {
+                const rows = report.items.map(item => `| ${item.type} | \`${sanitizeCell(item.skillName, 30)}\` | ${sanitizeCell(item.message, 80)} |`);
+                sections.push('\n| 级别 | Skill 名称 | 详情 |\n| :--- | :--- | :--- |\n' + rows.join('\n'));
+            }
+        }
+    }
+    return sections.join('\n');
+}

package/lib/renderers/status.d.ts

@@ -1,3 +1,4 @@
+import type { TelemetrySummary } from '../telemetry.js';
 export interface StatusSectionItem {
     repo?: string;
     number?: string;
@@ -21,3 +22,7 @@ export declare function parseStatusOutput(output: string): ParsedStatusReport;
  * Status 领域渲染器：负责用户跨仓待办大盘的 Markdown 格式化
  */
 export declare function renderStatusMarkdown(args: any, value: any): string;
+/**
+ * 渲染 DSH GitHub 工具链健康度与降级率审计报表
+ */
+export declare function renderHealthAuditMarkdown(summary: TelemetrySummary): string;

package/lib/renderers/status.js

@@ -90,6 +90,9 @@ export function parseStatusOutput(output) {
 export function renderStatusMarkdown(args, value) {
     if (!value)
         return '无返回内容';
+    if (value?.healthScore !== undefined || value?.degradationRate !== undefined || args?.action === 'health') {
+        return renderHealthAuditMarkdown(value);
+    }
     const report = value.parsed || parseStatusOutput(value.rawText || value.output || '');
     const renderSection = (title, icon, items, emptyText) => {
         if (!items || items.length === 0) {
@@ -122,3 +125,52 @@ export function renderStatusMarkdown(args, value) {
         '> 💡 **待办操作建议**: 可通过 `github_issue(action: \'view\')` 或 `github_pr(action: \'checkout\')` 快速检视对应议题并展开工作。',
     ].join('\n');
 }
+/**
+ * 渲染 DSH GitHub 工具链健康度与降级率审计报表
+ */
+export function renderHealthAuditMarkdown(summary) {
+    if (!summary)
+        return '无遥测健康度数据';
+    let badge = '🟢 极佳';
+    if (summary.statusLevel === 'NEEDS_ATTENTION') {
+        badge = '🔴 需关注';
+    }
+    else if (summary.statusLevel === 'GOOD') {
+        badge = '🟡 良好';
+    }
+    const successRate = summary.totalCalls > 0
+        ? `${((summary.successCount / summary.totalCalls) * 100).toFixed(1)}%`
+        : '100%';
+    const lines = [
+        '### 🩺 DSH GitHub 工具链健康度与降级率审计报表\n',
+        `- **综合健康分**: ${badge} (${summary.healthScore} / 100 分)`,
+        `- **统计样本量**: 最近 ${summary.totalCalls} 次 Agent 工具调用`,
+        `- **API 降级率**: \`${summary.degradationRate}%\` (${summary.degradedCount} 次触发降级链路)`,
+        `- **安全防御拦截**: ${summary.confirmBlockedCount + summary.scopeBlockedCount} 次 (含 ${summary.scopeBlockedCount} 次权限缺失，${summary.confirmBlockedCount} 次确认防线)`,
+        `- **执行成功率**: \`${successRate}\` (${summary.successCount} 成功, ${summary.failureCount} 失败)`,
+    ];
+    // 工具调用分布表
+    const toolNames = Object.keys(summary.toolStats || {});
+    if (toolNames.length > 0) {
+        const sorted = toolNames.sort((a, b) => summary.toolStats[b].total - summary.toolStats[a].total);
+        const rows = sorted.map((name) => {
+            const s = summary.toolStats[name];
+            const rate = s.total > 0 ? `${((s.success / s.total) * 100).toFixed(0)}%` : '100%';
+            let toolBadge = '🟢 正常';
+            if (s.degraded > 0)
+                toolBadge = '🟡 存在降级';
+            if (s.failed > 0 && s.success === 0)
+                toolBadge = '🔴 异常';
+            return `| \`${name}\` | ${s.total} | ${rate} | ${s.degraded} | ${toolBadge} |`;
+        });
+        lines.push('\n**核心工具调用分布:**', '| 工具名称 | 调用次数 | 成功率 | 降级次数 | 状态 |', '| :--- | :---: | :---: | :---: | :--- |', ...rows);
+    }
+    // 自愈优化建议
+    if (Array.isArray(summary.recommendations) && summary.recommendations.length > 0) {
+        lines.push('\n> 💡 **优化与自愈建议:**');
+        summary.recommendations.forEach((rec) => {
+            lines.push(`> - ${rec}`);
+        });
+    }
+    return lines.join('\n');
+}

package/lib/telemetry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DSH GitHub Flow - 运行时遥测审计与降级率收集器
+ *
+ * 遵循 /dsh-plugin-dev-skill 规范，利用 Cordis 的 tools/result 事件总线
+ * 建立内存中固定容量的轻量无锁环形队列，实现零外部数据库依赖、常驻内存严格 <200KB
+ * 的工业级运行时可观测性，量化分析 18 大工具矩阵的 API 降级率与健康度指标。
+ */
+export interface TelemetryRecord {
+    id: string;
+    timestamp: number;
+    toolName: string;
+    action?: string;
+    durationMs?: number;
+    success: boolean;
+    degraded: boolean;
+    scopeBlocked: boolean;
+    confirmBlocked: boolean;
+    errorType?: string;
+}
+export interface ToolUsageStat {
+    total: number;
+    success: number;
+    degraded: number;
+    failed: number;
+    blocked: number;
+}
+export interface TelemetrySummary {
+    totalCalls: number;
+    successCount: number;
+    failureCount: number;
+    degradedCount: number;
+    degradationRate: number;
+    scopeBlockedCount: number;
+    confirmBlockedCount: number;
+    healthScore: number;
+    statusLevel: 'EXCELLENT' | 'GOOD' | 'NEEDS_ATTENTION';
+    toolStats: Record<string, ToolUsageStat>;
+    recommendations: string[];
+}
+/**
+ * 内存固定容量环形队列（无锁、确定性内存上限）
+ */
+export declare class TelemetryRingBuffer {
+    private buffer;
+    private readonly capacity;
+    constructor(capacity?: number);
+    push(record: TelemetryRecord): void;
+    getAll(): TelemetryRecord[];
+    size(): number;
+    clear(): void;
+}
+/**
+ * 遥测收集与健康分析引擎
+ */
+export declare class TelemetryCollector {
+    private ringBuffer;
+    private callCounter;
+    constructor(capacity?: number);
+    /**
+     * 记录一次工具调用结果（Fail-Open 保护，绝不阻滞主流程）
+     */
+    recordCall(name: string, args: any, result: any, durationMs?: number): void;
+    /**
+     * 生成工具链健康度与降级率统计大盘
+     */
+    getSummary(): TelemetrySummary;
+    clear(): void;
+}
+/** 全局单例收集器实例 */
+export declare const defaultTelemetryCollector: TelemetryCollector;

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