dsh-github-flow 0.2.1 → 0.4.0

package/lib/tools/label.d.ts

@@ -0,0 +1,80 @@
+import type { GhExecutor } from '../executor.js';
+/**
+ * 校验并归一化 6 位十六进制颜色（去除前导 #）
+ */
+export declare function normalizeHexColor(rawColor?: string): string | undefined;
+export declare function createLabelTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            new_name: {
+                type: string;
+                description: string;
+            };
+            color: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            force: {
+                type: string;
+                description: string;
+            };
+            source_repo: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            search: {
+                type: string;
+                description: string;
+            };
+            sort: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            order: {
+                type: string;
+                enum: 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/label.js

@@ -0,0 +1,237 @@
+import { renderLabelMarkdown } from '../renderers/markdown.js';
+/**
+ * 校验并归一化 6 位十六进制颜色（去除前导 #）
+ */
+export function normalizeHexColor(rawColor) {
+    if (!rawColor)
+        return undefined;
+    const clean = rawColor.trim().replace(/^#/, '').trim();
+    if (!/^[0-9a-fA-F]{6}$/.test(clean)) {
+        throw new Error(`标签颜色必须为 6 位十六进制字符串（如 "d73a4a" 或 "#d73a4a"），当前为: "${rawColor}"`);
+    }
+    return clean;
+}
+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 createLabelTool(executor) {
+    return {
+        name: 'github_label',
+        description: '管理 GitHub 仓库标签体系 (Labels)：查看标签列表、创建新标签、编辑修改现有标签、克隆跨仓库标签体系 (clone) 以及安全删除标签。删除操作不可逆且会解绑议题，需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'create', 'edit', 'delete', 'clone'],
+                    description: 'Label 操作类型。list 查看列表、create 新建、edit 修改、delete 物理删除（需 confirm）、clone 跨仓库克隆同步。',
+                },
+                repo: {
+                    type: 'string',
+                    description: '目标仓库 [owner/repo]，留空则识别当前工作区仓库。',
+                },
+                name: {
+                    type: 'string',
+                    description: '标签名称（create, edit, delete 动作必需）。',
+                },
+                new_name: {
+                    type: 'string',
+                    description: '新标签名称（edit 动作重命名标签时使用）。',
+                },
+                color: {
+                    type: 'string',
+                    description: '6 位十六进制色值（create, edit 动作可选，例如 "d73a4a" 或 "#d73a4a"）。',
+                },
+                description: {
+                    type: 'string',
+                    description: '标签描述（create, edit 动作可选）。',
+                },
+                force: {
+                    type: 'boolean',
+                    description: '是否强制覆盖（create 动作同名时更新、clone 动作冲突时覆盖；默认 false）。',
+                },
+                source_repo: {
+                    type: 'string',
+                    description: '源仓库全名 [owner/repo]（clone 动作必需，例如 "cli/cli"）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回标签数量上限（list 动作使用，默认 30）。',
+                },
+                search: {
+                    type: 'string',
+                    description: '按标签名称或描述过滤检索（list 动作使用）。',
+                },
+                sort: {
+                    type: 'string',
+                    enum: ['created', 'name'],
+                    description: '排序字段（list 动作使用，默认 created）。',
+                },
+                order: {
+                    type: 'string',
+                    enum: ['asc', 'desc'],
+                    description: '排序方向（list 动作使用，默认 asc）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（delete 动作必需）。未传 true 时输出影响评估报告并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderLabelMarkdown(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 = ['label', 'list', ...repoArgs, '--json', 'name,color,description'];
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 30;
+                    listCmd.push('-L', String(limit));
+                    if (args.search) {
+                        listCmd.push('-S', String(args.search));
+                    }
+                    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 'create': {
+                    if (!args.name) {
+                        throw new Error('创建标签时 `name` 参数为必填项。');
+                    }
+                    const color = normalizeHexColor(args.color);
+                    const createCmd = ['label', 'create', args.name, ...repoArgs];
+                    if (color) {
+                        createCmd.push('-c', color);
+                    }
+                    if (args.description) {
+                        createCmd.push('-d', args.description);
+                    }
+                    if (args.force) {
+                        createCmd.push('-f');
+                    }
+                    const res = await executor.run(createCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        name: args.name,
+                        message: `✅ 成功在仓库 ${repoTarget} 创建标签 "${args.name}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                case 'edit': {
+                    if (!args.name) {
+                        throw new Error('编辑标签时 `name` 参数为必填项。');
+                    }
+                    const color = normalizeHexColor(args.color);
+                    const editCmd = ['label', 'edit', args.name, ...repoArgs];
+                    if (args.new_name) {
+                        editCmd.push('-n', args.new_name);
+                    }
+                    if (color) {
+                        editCmd.push('-c', color);
+                    }
+                    if (args.description !== undefined) {
+                        editCmd.push('-d', args.description);
+                    }
+                    const res = await executor.run(editCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        name: args.new_name || args.name,
+                        message: `✅ 成功更新仓库 ${repoTarget} 标签 "${args.name}"` + (args.new_name ? `（重命名为 "${args.new_name}"）` : ''),
+                        detail: res.rawOutput || '',
+                    };
+                }
+                case 'delete': {
+                    if (!args.name) {
+                        throw new Error('删除标签时 `name` 参数为必填项。');
+                    }
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            action: 'delete',
+                            name: args.name,
+                            repo: repoTarget,
+                            warning: `⚠️ 高危破坏性操作：即将删除仓库 ${repoTarget} 的标签 "${args.name}"`,
+                            impact: `删除标签不可逆，且会导致目标仓库内所有已打上该标签的 Issue 与 PR 自动解绑该标记。`,
+                            requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_label(action: 'delete', name: '${args.name}', confirm: true)\``,
+                        };
+                    }
+                    const deleteCmd = ['label', 'delete', args.name, '--yes', ...repoArgs];
+                    const res = await executor.run(deleteCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        name: args.name,
+                        message: `🗑️ 成功在仓库 ${repoTarget} 删除标签 "${args.name}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                case 'clone': {
+                    if (!args.source_repo) {
+                        throw new Error('克隆标签时 `source_repo` 源仓库参数为必填项（格式: [owner/repo]）。');
+                    }
+                    const cloneCmd = ['label', 'clone', args.source_repo, ...repoArgs];
+                    if (args.force) {
+                        cloneCmd.push('-f');
+                    }
+                    const res = await executor.run(cloneCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        source: args.source_repo,
+                        destination: repoTarget,
+                        message: `🏷️ 成功将源仓库 ${args.source_repo} 的标签体系克隆同步到 ${repoTarget}` + (args.force ? '（已覆盖同名冲突标签）' : ''),
+                        detail: res.rawOutput || '',
+                    };
+                }
+                default:
+                    throw new Error(`不支持的 label 操作: "${args.action}"。可选值: list, create, edit, delete, clone。`);
+            }
+        },
+    };
+}

package/lib/tools/pr.d.ts

@@ -1,4 +1,5 @@
 import type { GhExecutor } from '../executor.js';
+export { extractImageUrls as extractPrImageUrls, validateAttachPaths } from './image-utils.js';
 export declare function createPrTool(executor: GhExecutor): {
     name: string;
     description: string;
@@ -52,6 +53,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            undo: {
+                type: string;
+                description: string;
+            };
             state: {
                 type: string;
                 enum: string[];
@@ -84,6 +89,13 @@ export declare function createPrTool(executor: GhExecutor): {
                 };
                 description: string;
             };
+            attach_images: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: string[];
     };

package/lib/tools/pr.js

@@ -1,5 +1,6 @@
+import { compareGhVersions } from '../executor.js';
 import { renderPrMarkdown } from '../renderers/markdown.js';
-import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
+import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls, validateAttachPaths } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -9,6 +10,8 @@ function normalizeOutput(data) {
     }
     return { result: data !== undefined && data !== null ? data : '' };
 }
+// 共享图片工具链的同名再导出：保持路径与单测稳定
+export { extractImageUrls as extractPrImageUrls, validateAttachPaths } from './image-utils.js';
 export function createPrTool(executor) {
     return {
         name: 'github_pr',
@@ -18,8 +21,8 @@ export function createPrTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status', 'view_images'],
-                    description: 'PR 操作类型。view_images 下载正文与评论中的图片（UI 变更对比图、复现截图等）到本地并以图片内容块返回，供 Agent 审查时直接查看。',
+                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status', 'view_images', 'ready', 'revert', 'update_branch', 'comment', 'edit'],
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片到本地；create/edit/comment 支持 attach_images 附件上传；merge/revert 需 confirm: true。',
                 },
                 pr_number: {
                     type: 'number',
@@ -61,7 +64,11 @@ export function createPrTool(executor) {
                 },
                 delete_branch: {
                     type: 'boolean',
-                    description: '合并后是否删除源分支（merge 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                    description: '合并/revert 后是否删除源分支（merge、revert 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                },
+                undo: {
+                    type: 'boolean',
+                    description: 'ready 动作可选：反向操作，把 PR 转回 Draft（gh 原生 --undo）。',
                 },
                 state: {
                     type: 'string',
@@ -93,6 +100,11 @@ export function createPrTool(executor) {
                     items: { type: 'string' },
                     description: 'view_images 可选：仅下载指定 URL 的图片（从 view 返回的 images 清单中选取，不在清单内的会被拒绝）。留空下载全部（正文+评论）。',
                 },
+                attach_images: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '本地图片/附件路径列表（create, edit, comment 动作使用，需 gh ≥ 2.99；禁止 URL，单批上限 50 个）。',
+                },
             },
             required: ['action'],
         },
@@ -117,6 +129,18 @@ export function createPrTool(executor) {
             }
             const repoArgs = ['-R', repoTarget];
             const runOpts = { cwd, sessionId };
+            const appendAttachFlags = async (cmd, attachImages) => {
+                const attachPaths = validateAttachPaths(attachImages, cwd);
+                if (attachPaths.length > 0) {
+                    const version = await executor.getGhVersion();
+                    if (version && compareGhVersions(version, '2.99.0') < 0) {
+                        throw new Error(`附件上传能力 (\`--attach\`) 需要 GitHub CLI 版本 ≥ 2.99.0，当前版本为: ${version}。\n请升级 gh（Windows: \`winget upgrade GitHub.cli\`，macOS: \`brew upgrade gh\`）后再试。`);
+                    }
+                    for (const p of attachPaths) {
+                        cmd.push('--attach', p);
+                    }
+                }
+            };
             switch (args.action) {
                 case 'list': {
                     const listCmd = ['pr', 'list', ...repoArgs, '--json', 'number,title,author,headRefName,isDraft,state,updatedAt,mergedAt,url'];
@@ -257,6 +281,7 @@ export function createPrTool(executor) {
                     const dryRun = args.dry_run === true;
                     if (dryRun)
                         createCmd.push('--dry-run');
+                    await appendAttachFlags(createCmd, args.attach_images);
                     const res = await executor.run(createCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
@@ -303,6 +328,73 @@ export function createPrTool(executor) {
                         throw new Error(res.error);
                     return { message: 'PR 合并完成', output: res.rawOutput };
                 }
+                // ---- 变更面新增（S3）----
+                case 'ready': {
+                    if (!args.pr_number)
+                        throw new Error('ready 操作必须提供 pr_number');
+                    // Draft→Ready；gh 原生支持 --undo 反向（转回 draft），完整可逆，免 confirm
+                    const cmd = ['pr', 'ready', String(args.pr_number), ...repoArgs];
+                    if (args.undo === true)
+                        cmd.push('--undo');
+                    const res = await executor.run(cmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 已${args.undo === true ? '转回 Draft' : '从 Draft 转为 Ready（进入正式评审）'}` };
+                }
+                case 'revert': {
+                    if (!args.pr_number)
+                        throw new Error('revert 操作必须提供 pr_number');
+                    // revert 在远端创建反向提交与新 PR——虽不碰原 PR，但产生新实体，按 merge 级 confirm（D5）
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将对 PR #${args.pr_number} 创建反向提交（revert）。`,
+                            impact: '将在远端创建反向提交并生成新的 revert PR——这是新增远端实体，不是本地操作。',
+                            requiredAction: '如确认执行，请向用户明确确认并附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const revertCmd = ['pr', 'revert', String(args.pr_number), ...repoArgs];
+                    if (args.delete_branch === true)
+                        revertCmd.push('--delete-branch');
+                    const res = await executor.run(revertCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 的反向提交已创建`, url: res.rawOutput };
+                }
+                case 'update_branch': {
+                    if (!args.pr_number)
+                        throw new Error('update_branch 操作必须提供 pr_number');
+                    // 等价 repo sync 的单 PR 版（push merge commit 到 PR 分支）；恰是「分支落后」
+                    // 的自愈动作，confirm 摩擦会阻碍 Agent 自愈闭环（D6），输出同步摘要即可
+                    const res = await executor.run(['pr', 'update-branch', String(args.pr_number), ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 分支已从基准分支同步更新`, output: res.rawOutput };
+                }
+                case 'comment': {
+                    if (!args.pr_number || !args.body)
+                        throw new Error('comment 必须提供 pr_number 和 body');
+                    const commentCmd = ['pr', 'comment', String(args.pr_number), ...repoArgs, '--body', args.body];
+                    await appendAttachFlags(commentCmd, args.attach_images);
+                    const res = await executor.run(commentCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: 'PR 评论发布成功', output: res.rawOutput };
+                }
+                case 'edit': {
+                    if (!args.pr_number)
+                        throw new Error('edit 操作必须提供 pr_number');
+                    const editCmd = ['pr', 'edit', String(args.pr_number), ...repoArgs];
+                    if (args.title)
+                        editCmd.push('--title', args.title);
+                    if (args.body)
+                        editCmd.push('--body', args.body);
+                    await appendAttachFlags(editCmd, args.attach_images);
+                    const res = await executor.run(editCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `PR #${args.pr_number} 更新成功`, output: res.rawOutput };
+                }
                 default:
                     throw new Error(`未知的 PR 操作: ${args.action}`);
             }

package/lib/tools/repo.d.ts

@@ -29,6 +29,14 @@ export declare function createRepoTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            path: {
+                type: string;
+                description: string;
+            };
+            ref: {
+                type: string;
+                description: string;
+            };
             limit: {
                 type: string;
                 description: string;