dsh-github-flow 0.4.0 → 0.6.0

package/lib/tools/project.js

@@ -0,0 +1,241 @@
+import { renderProjectMarkdown } 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 : '' };
+}
+/**
+ * 检测错误信息是否属于 Scope 权限不足，并返回标准自愈对象
+ */
+export function checkScopeRequired(errorMsg, scope, command, tool) {
+    const lower = (errorMsg || '').toLowerCase();
+    if (lower.includes('missing required scopes') || lower.includes('needs the') || lower.includes('scope')) {
+        return {
+            status: 'SCOPE_REQUIRED',
+            scope,
+            command,
+            tool,
+        };
+    }
+    return null;
+}
+export function createProjectTool(executor) {
+    return {
+        name: 'github_project',
+        description: '管理 GitHub Projects v2 项目看板与任务规划：查看项目列表与卡片条目、关联 Issue/PR 到看板、创建草稿任务、删除看板条目。未授权时提供平台感知自愈命令。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'item-list', 'item-add', 'item-create', 'item-delete'],
+                    description: 'Project 操作类型。list 查看项目列表、view 查看项目详情、item-list 查看看板条目、item-add 添加现有Issue/PR、item-create 创建草稿条目、item-delete 删除条目。',
+                },
+                owner: {
+                    type: 'string',
+                    description: '项目所属用户或组织（缺省为 "@me" 即当前用户）。',
+                },
+                project_number: {
+                    type: 'number',
+                    description: '项目数字编号（view, item-list, item-add, item-create 动作必需）。',
+                },
+                item_id: {
+                    type: 'string',
+                    description: '项目条目唯一标识 ID（item-delete 动作必需）。',
+                },
+                url: {
+                    type: 'string',
+                    description: '要添加到项目的 Issue 或 PR URL（item-add 动作必需）。',
+                },
+                title: {
+                    type: 'string',
+                    description: '草稿条目标题（item-create 动作必需）。',
+                },
+                body: {
+                    type: 'string',
+                    description: '草稿条目正文描述（item-create 动作可选）。',
+                },
+                query: {
+                    type: 'string',
+                    description: '过滤查询语法（item-list 动作可选，如 "is:open assignee:@me"）。',
+                },
+                closed: {
+                    type: 'boolean',
+                    description: '是否包含已关闭的项目（list 动作使用，默认 false）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回数量上限（list 与 item-list 动作使用，默认 30）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '危险操作确认标记（item-delete 动作必需）。未确认时输出影响评估并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderProjectMarkdown(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 owner = typeof args.owner === 'string' && args.owner.trim() ? args.owner.trim() : '@me';
+            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 = [
+                        'project', 'list',
+                        '--format', 'json',
+                        '--owner', owner,
+                        '-L', String(limit),
+                    ];
+                    if (args.closed === true)
+                        listCmd.push('--closed');
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'view': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('view 操作必须提供 project_number（项目数字编号）');
+                    }
+                    const viewCmd = [
+                        'project', 'view', String(args.project_number),
+                        '--format', 'json',
+                        '--owner', owner,
+                    ];
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'item-list': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-list 操作必须提供 project_number（项目数字编号）');
+                    }
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
+                    const itemCmd = [
+                        'project', 'item-list', String(args.project_number),
+                        '--format', 'json',
+                        '--owner', owner,
+                        '-L', String(limit),
+                    ];
+                    if (args.query)
+                        itemCmd.push('--query', String(args.query).trim());
+                    const res = await executor.run(itemCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'read:project', 'gh auth refresh -s read:project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'item-add': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-add 操作必须提供 project_number（项目数字编号）');
+                    }
+                    if (!args.url || typeof args.url !== 'string' || !args.url.trim()) {
+                        throw new Error('item-add 操作必须提供 url（Issue 或 PR 的完整链接）');
+                    }
+                    const addCmd = [
+                        'project', 'item-add', String(args.project_number),
+                        '--owner', owner,
+                        '--url', args.url.trim(),
+                        '--format', 'json',
+                    ];
+                    const res = await executor.run(addCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `已成功将条目添加到项目 #${args.project_number}`,
+                        output: res.rawOutput || 'Item added',
+                    };
+                }
+                case 'item-create': {
+                    if (!args.project_number || typeof args.project_number !== 'number') {
+                        throw new Error('item-create 操作必须提供 project_number（项目数字编号）');
+                    }
+                    if (!args.title || typeof args.title !== 'string' || !args.title.trim()) {
+                        throw new Error('item-create 操作必须提供 title（草稿条目标题）');
+                    }
+                    const createCmd = [
+                        'project', 'item-create', String(args.project_number),
+                        '--owner', owner,
+                        '--title', args.title.trim(),
+                        '--format', 'json',
+                    ];
+                    if (args.body)
+                        createCmd.push('--body', String(args.body).trim());
+                    const res = await executor.run(createCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `已成功在项目 #${args.project_number} 中创建条目「${args.title.trim()}」`,
+                        output: res.rawOutput || 'Draft item created',
+                    };
+                }
+                case 'item-delete': {
+                    if (!args.item_id || typeof args.item_id !== 'string' || !args.item_id.trim()) {
+                        throw new Error('item-delete 操作必须提供 item_id（条目唯一 ID）');
+                    }
+                    const cleanItemId = args.item_id.trim();
+                    // 确认防线拦截
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 删除确认拦截：你即将从看板中删除条目（ID: ${cleanItemId}）。`,
+                            impact: '该操作将从项目看板中物理移除该条目（若是关联的 Issue/PR，实体不会被删除，仅解除看板关联）。',
+                            requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const deleteCmd = [
+                        'project', 'item-delete',
+                        '--owner', owner,
+                        '--id', cleanItemId,
+                        '--format', 'json',
+                    ];
+                    const res = await executor.run(deleteCmd, runOpts);
+                    if (!res.ok) {
+                        const scopeFix = checkScopeRequired(res.error || '', 'project', 'gh auth refresh -s project', 'github_project');
+                        if (scopeFix)
+                            return scopeFix;
+                        throw new Error(res.error);
+                    }
+                    return {
+                        message: `条目「${cleanItemId}」已从项目看板中成功删除`,
+                        output: res.rawOutput || 'Item deleted',
+                    };
+                }
+                default:
+                    throw new Error(`未知的 Project 操作: ${args.action}`);
+            }
+        },
+    };
+}

package/lib/tools/repo.js

@@ -239,7 +239,19 @@ export function createRepoTool(executor) {
                     if (content.includes('\0')) {
                         throw new Error(`「${args.path}」是二进制文件（检测到 NUL 字节），不适合文本读取。请改用 github_api(endpoint: 'repos/${owner}/${repoName}/contents/${args.path.split('/').map(encodeURIComponent).join('/')}', raw: true, binary 场景自行落盘) 获取字节流。`);
                     }
-                    return { path: args.path, ref: args.ref, content, size: content.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                    const resultObj = {
+                        path: args.path,
+                        content,
+                        size: content.length,
+                    };
+                    if (args.ref) {
+                        resultObj.ref = args.ref;
+                    }
+                    if (res.degraded) {
+                        resultObj.degraded = res.degraded;
+                        resultObj.degradedReason = res.degradedReason;
+                    }
+                    return resultObj;
                 }
                 case 'read_dir': {
                     let repoTarget = args.repo;

package/lib/tools/skill.d.ts

@@ -43,6 +43,29 @@ export declare function createSkillTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            directory: {
+                type: string;
+                description: string;
+            };
+            dry_run: {
+                type: string;
+                description: string;
+            };
+            fix: {
+                type: string;
+                description: string;
+            };
+            tag: {
+                type: string;
+                description: string;
+            };
+            skill_names: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
             confirm: {
                 type: string;
                 description: string;
@@ -59,5 +82,5 @@ export declare function createSkillTool(executor: GhExecutor): {
             text: string;
         }[];
     };
-    execute(args: any, execContext: any): Promise<Record<string, any>>;
+    execute(args: any, execContext: any): Promise<Record<string, any> | import("../renderers/skill.js").SkillPublishReport>;
 };

package/lib/tools/skill.js

@@ -1,4 +1,6 @@
-import { renderSkillMarkdown } from '../renderers/markdown.js';
+import path from 'node:path';
+import fs from 'node:fs';
+import { renderSkillMarkdown, parseSkillPublishOutput } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -11,14 +13,14 @@ function normalizeOutput(data) {
 export function createSkillTool(executor) {
     return {
         name: 'github_skill',
-        description: '通过 GitHub CLI 官方生态发现与管理 Agent Skills：跨仓库检索开源 Skills、预览 SKILL.md 内容、安装到本地 Agent 宿主（Claude Code / Cursor / Copilot 等）、查看已安装列表。install 会写入本地磁盘，需 confirm: true。基于 gh CLI preview 特性（需 gh >= 2.9x）。',
+        description: '通过 GitHub CLI 官方生态发现与管理 Agent Skills：跨仓库检索开源 Skills、预览 SKILL.md 内容、安装到本地 Agent 宿主（Claude Code / Cursor / Copilot 等）、查看已安装列表、合规自检与安全发布（publish）以及检查与同步更新（update）。install 会写入磁盘需 confirm；publish 默认 --dry-run 自检，正式发布需 tag 与 confirm；update 默认 --dry-run 检查。基于 gh CLI preview 特性（需 gh >= 2.9x）。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['search', 'preview', 'install', 'list'],
-                    description: 'Skill 操作类型。',
+                    enum: ['search', 'preview', 'install', 'list', 'publish', 'update'],
+                    description: 'Skill 操作类型。search 检索、preview 预览、install 安装、list 查看已安装、publish 校验/发布、update 检查与同步更新。',
                 },
                 query: {
                     type: 'string',
@@ -53,9 +55,30 @@ export function createSkillTool(executor) {
                     type: 'number',
                     description: '搜索返回数量上限（search 动作使用，默认 15）。',
                 },
+                directory: {
+                    type: 'string',
+                    description: '待检查或发布的技能目录（publish 动作使用，缺省为当前工作区根目录）。',
+                },
+                dry_run: {
+                    type: 'boolean',
+                    description: '是否仅进行合规性验证而不发布（publish 动作使用，默认 true，零副作用安全验证模式）。',
+                },
+                fix: {
+                    type: 'boolean',
+                    description: '是否自动修复问题（如剥离残留的安装元数据，publish 动作使用，默认 false）。',
+                },
+                tag: {
+                    type: 'string',
+                    description: '发布的版本 Tag（如 "v1.0.0"），正式发布（dry_run: false）时必填（防交互式挂起）。',
+                },
+                skill_names: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '要更新的特定 Skill 名称列表（update 动作可选）。',
+                },
                 confirm: {
                     type: 'boolean',
-                    description: '安装操作确认标志。install 会向本地磁盘写入文件，未传 true 时仅输出将要执行的安装预览。',
+                    description: '高危操作确认标志。install 写入本地磁盘、publish 正式创建 Release 时必需。未传 true 时输出影响评估并拦截。',
                 },
             },
             required: ['action'],
@@ -138,6 +161,93 @@ export function createSkillTool(executor) {
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'publish': {
+                    const isFix = args.fix === true;
+                    const isDryRun = args.dry_run !== false && !isFix;
+                    const targetDir = typeof args.directory === 'string' && args.directory.trim() ? args.directory.trim() : undefined;
+                    // 1. 目录存在性前置安全校验
+                    if (targetDir) {
+                        const resolvedPath = path.resolve(cwd, targetDir);
+                        if (!fs.existsSync(resolvedPath)) {
+                            throw new Error(`指定的技能目录不存在: ${targetDir}`);
+                        }
+                    }
+                    // 2. 正式发布分支（dry_run 为 false 且非 fix 模式）
+                    if (!isDryRun && !isFix) {
+                        // 防线 1: 必须显式指定版本 tag，防止 CLI 弹出交互式向导导致子进程永久挂起
+                        if (!args.tag || typeof args.tag !== 'string' || !args.tag.trim()) {
+                            throw new Error('正式发布 Skill（dry_run: false）必须提供版本 tag（如 "v1.0.0"），以防止 CLI 尝试进入交互式向导导致进程挂起');
+                        }
+                        const cleanTag = args.tag.trim();
+                        // 防线 2: 破坏性发布二级确认拦截（创建 Release 与打 Tag 属于公开制品发布）
+                        if (args.confirm !== true) {
+                            return {
+                                status: 'AWAITING_CONFIRMATION',
+                                warning: `⚠️ 发布确认拦截：你即将正式发布 Agent Skill 并创建 GitHub Release（Tag: ${cleanTag}）。`,
+                                impact: `该操作将在仓库中打上「agent-skills」Topic、创建 Git Tag「${cleanTag}」并发布正式 GitHub Release，向所有用户公开提供该版本。`,
+                                requiredAction: `如确认发布，请核实版本号并在参数中附加 \`confirm: true\` 重新调用。`,
+                            };
+                        }
+                        const publishCmd = ['skill', 'publish'];
+                        if (targetDir)
+                            publishCmd.push(targetDir);
+                        publishCmd.push('--tag', cleanTag);
+                        const res = await executor.run(publishCmd, { ...runOpts, rawText: true, timeoutMs: 120_000 });
+                        if (!res.ok) {
+                            if (res.rawOutput) {
+                                return parseSkillPublishOutput(res.rawOutput, res.error || '', false, 'publish', targetDir, cleanTag);
+                            }
+                            throw new Error(res.error || '发布 Skill 失败');
+                        }
+                        return parseSkillPublishOutput(res.rawOutput || '', '', true, 'publish', targetDir, cleanTag);
+                    }
+                    // 3. 自动剥离安装元数据分支 (--fix)
+                    if (isFix) {
+                        const fixCmd = ['skill', 'publish'];
+                        if (targetDir)
+                            fixCmd.push(targetDir);
+                        fixCmd.push('--fix');
+                        const res = await executor.run(fixCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                        const output = res.rawOutput || (res.ok ? '' : res.error || '');
+                        return parseSkillPublishOutput(output, res.error || '', res.ok, 'fix', targetDir);
+                    }
+                    // 4. 默认只读自检分支 (--dry-run)
+                    const dryRunCmd = ['skill', 'publish'];
+                    if (targetDir)
+                        dryRunCmd.push(targetDir);
+                    dryRunCmd.push('--dry-run');
+                    const res = await executor.run(dryRunCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    const combinedOutput = res.rawOutput || '';
+                    const stderrText = res.error || '';
+                    return parseSkillPublishOutput(combinedOutput, stderrText, res.ok, 'dry-run', targetDir);
+                }
+                case 'update': {
+                    const isDryRun = args.dry_run !== false;
+                    const updateCmd = ['skill', 'update'];
+                    if (isDryRun)
+                        updateCmd.push('--dry-run');
+                    if (args.all === true)
+                        updateCmd.push('--all');
+                    if (Array.isArray(args.skill_names) && args.skill_names.length > 0) {
+                        args.skill_names.forEach((name) => {
+                            if (name && typeof name === 'string' && name.trim()) {
+                                updateCmd.push(name.trim());
+                            }
+                        });
+                    }
+                    else if (args.skill_name && typeof args.skill_name === 'string') {
+                        updateCmd.push(args.skill_name.trim());
+                    }
+                    const res = await executor.run(updateCmd, { ...runOpts, rawText: true, timeoutMs: 90_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        mode: isDryRun ? 'dry-run' : 'update',
+                        action: 'update',
+                        message: isDryRun ? 'Agent Skills 更新检查完成（Dry-run 只读模式）' : 'Agent Skills 已完成更新同步',
+                        output: res.rawOutput || 'All skills up to date.',
+                    };
+                }
                 default:
                     throw new Error(`未知的 Skill 操作: ${args.action}`);
             }

package/lib/tools/status.d.ts

@@ -1,5 +1,6 @@
 import type { GhExecutor } from '../executor.js';
-export declare function createStatusTool(executor: GhExecutor): {
+import { TelemetryCollector } from '../telemetry.js';
+export declare function createStatusTool(executor: GhExecutor, telemetryCollector?: TelemetryCollector): {
     name: string;
     description: string;
     parameters: {
@@ -32,7 +33,7 @@ export declare function createStatusTool(executor: GhExecutor): {
             text: string;
         }[];
     };
-    execute(args: any, execContext: any): Promise<{
+    execute(args: any, execContext: any): Promise<import("../telemetry.js").TelemetrySummary | {
         parsed: import("../renderers/status.js").ParsedStatusReport;
         rawText: string;
     }>;

package/lib/tools/status.js

@@ -1,15 +1,16 @@
 import { renderStatusMarkdown, parseStatusOutput } from '../renderers/markdown.js';
-export function createStatusTool(executor) {
+import { defaultTelemetryCollector } from '../telemetry.js';
+export function createStatusTool(executor, telemetryCollector) {
     return {
         name: 'github_status',
-        description: '聚合展示当前登录用户的跨仓库全局待办与动态大盘：包括指派给我的 Issues、指派给我的 PR、等待我评审的 PR、近期 @提及 以及订阅仓库的最新动态。无需指定单仓，账号维度一站式概览。',
+        description: '聚合展示当前登录用户的跨仓库全局待办与动态大盘（view），或审计当前工具链运行时健康度、API 降级率与自愈建议（health）。无需指定单仓，账号与系统维度一站式概览。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['view'],
-                    description: '操作类型，默认为 view（查看全局待办看板）。',
+                    enum: ['view', 'health'],
+                    description: '操作类型。view 查看个人全局待办与动态看板（默认）、health 查看工具链健康度与 API 降级率审计报表。',
                 },
                 org: {
                     type: 'string',
@@ -29,6 +30,10 @@ export function createStatusTool(executor) {
             },
         },
         async execute(args, execContext) {
+            if (args?.action === 'health') {
+                const collector = telemetryCollector || defaultTelemetryCollector;
+                return collector.getSummary();
+            }
             const cwd = execContext?.cwd || process.cwd();
             const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
             const statusCmd = ['status'];