dsh-github-flow 0.1.8 → 0.2.1

package/lib/tools/issue.js

@@ -1,3 +1,5 @@
+import { renderIssueMarkdown } from '../renderers/markdown.js';
+import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -7,21 +9,23 @@ function normalizeOutput(data) {
     }
     return { result: data !== undefined && data !== null ? data : '' };
 }
+// 共享图片工具链的同名再导出：phase8 测试直接 import 本模块，保持路径稳定
+export { extractImageUrls as extractIssueImageUrls } from './image-utils.js';
 export function createIssueTool(executor) {
     return {
         name: 'github_issue',
-        description: '管理 GitHub Issues。支持查看 Issue 列表、详情、创建新 Issue、追加评论以及关闭 Issue。',
+        description: '管理 GitHub Issues。支持查看 Issue 列表、详情、创建新 Issue、追加评论、关闭 Issue、编辑 Issue 以及关联创建本地开发分支 (develop)。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen'],
-                    description: 'Issue 操作类型。',
+                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop', 'view_images'],
+                    description: 'Issue 操作类型。view_images 下载正文内的图片到本地并返回可渲染的图片内容块（Agent 可直接"看"用户报障截图）。',
                 },
                 issue_number: {
                     type: 'number',
-                    description: 'Issue 编号（view, comment, close, reopen 时使用）。',
+                    description: 'Issue 编号（view, comment, close, reopen, edit, develop 时使用）。',
                 },
                 repo: {
                     type: 'string',
@@ -29,21 +33,53 @@ export function createIssueTool(executor) {
                 },
                 title: {
                     type: 'string',
-                    description: 'Issue 标题（create 时使用）。',
+                    description: 'Issue 标题（create 或 edit 时使用）。',
                 },
                 body: {
                     type: 'string',
-                    description: 'Issue 描述正文或追加评论内容。',
+                    description: 'Issue 描述正文或追加评论内容（create, comment, edit 时使用）。',
                 },
                 labels: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: '标签名称列表。',
+                    description: '标签名称列表（create 或 list 动作筛选使用）。',
                 },
                 assignees: {
                     type: 'array',
                     items: { type: 'string' },
-                    description: '被指派人的 GitHub 登录名列表。',
+                    description: '被指派人的 GitHub 登录名列表（create 或 list 动作筛选使用）。',
+                },
+                state: {
+                    type: 'string',
+                    enum: ['open', 'closed', 'all'],
+                    description: 'Issue 状态过滤（list 动作使用，可选 open, closed, all，默认 open）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回 Issue 数量上限（list 动作使用，默认 20，建议最大不超过 100）。',
+                },
+                branch_name: {
+                    type: 'string',
+                    description: '开发分支名称（develop 动作使用，例如 "fix-auth-bug"）。',
+                },
+                add_labels: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '要追加的标签列表（edit 动作使用）。',
+                },
+                remove_labels: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '要移除的标签列表（edit 动作使用）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（close 动作必需）。若为 false 则仅输出待关闭警告。',
+                },
+                image_urls: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'view_images 可选：仅下载指定 URL 的图片（从 view 返回的 images 清单中选取，不在清单内的会被拒绝）。留空下载全部（正文+评论）。',
                 },
             },
             required: ['action'],
@@ -51,15 +87,9 @@ export function createIssueTool(executor) {
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                if (!value)
-                    return [{ type: 'text', text: '无返回内容' }];
-                if (typeof value.result === 'string') {
-                    return [{ type: 'text', text: value.result }];
-                }
-                if (Array.isArray(value.items)) {
-                    return [{ type: 'text', text: JSON.stringify(value.items, null, 2) }];
-                }
-                return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+                // view_images 的图片以宿主 image 内容块输出：模型与人类都能直接看到图，
+                // base64 会污染上下文（一张截图 ~88KB），引用落盘文件由宿主按需加载
+                return [{ type: 'text', text: renderIssueMarkdown(args, value) }, ...buildImageBlocks(value)];
             },
         },
         async execute(args, execContext) {
@@ -79,7 +109,23 @@ export function createIssueTool(executor) {
             const runOpts = { cwd, sessionId };
             switch (args.action) {
                 case 'list': {
-                    const res = await executor.run(['issue', 'list', ...repoArgs, '--json', 'number,title,state,author,labels,updatedAt', '-L', '20'], runOpts);
+                    const listCmd = ['issue', 'list', ...repoArgs, '--json', 'number,title,state,author,labels,updatedAt,url'];
+                    if (args.state) {
+                        listCmd.push('--state', args.state);
+                    }
+                    if (args.labels && Array.isArray(args.labels) && args.labels.length > 0) {
+                        for (const l of args.labels) {
+                            listCmd.push('--label', l);
+                        }
+                    }
+                    if (args.assignees && Array.isArray(args.assignees) && args.assignees.length > 0) {
+                        // gh issue list 的 --assignee 仅支持单账号或 @me，传逗号连接会导致 GraphQL 报用户未找到
+                        listCmd.push('--assignee', args.assignees[0]);
+                    }
+                    // 显式 limit 优先；缺省回退 executor.defaultListLimit（用户可在插件配置中调整）
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : Math.min(executor.defaultListLimit ?? 20, 100);
+                    listCmd.push('-L', String(limit));
+                    const res = await executor.run(listCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
@@ -90,7 +136,68 @@ export function createIssueTool(executor) {
                     const res = await executor.run(['issue', 'view', String(args.issue_number), ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,comments,url'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
-                    return normalizeOutput(res.data || res.rawOutput);
+                    const out = normalizeOutput(res.data || res.rawOutput);
+                    // 附带图片 URL 清单（正文+评论，与 view_images 提取范围同源）：
+                    // Agent 按正文里的原始 URL 决策，需要看图时用 image_urls 精准选取
+                    const bodies = [typeof out.body === 'string' ? out.body : ''];
+                    if (Array.isArray(out.comments)) {
+                        for (const c of out.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    out.images = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    return out;
+                }
+                case 'view_images': {
+                    if (!args.issue_number)
+                        throw new Error('view_images 操作必须提供 issue_number');
+                    // 第一步：取正文+评论提取图片 URL（与 view 清单同源）
+                    const detail = await executor.run(['issue', 'view', String(args.issue_number), ...repoArgs, '--json', 'body,comments'], runOpts);
+                    if (!detail.ok)
+                        throw new Error(detail.error);
+                    const d = detail.data && typeof detail.data === 'object' ? detail.data : {};
+                    const bodies = [typeof d.body === 'string' ? d.body : ''];
+                    if (Array.isArray(d.comments)) {
+                        for (const c of d.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    const extracted = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    if (extracted.length === 0) {
+                        return { message: `Issue #${args.issue_number} 正文与评论中未发现图片附件。` };
+                    }
+                    // 第二步：目标选择——不传 image_urls 下载全部；传入则与正文清单
+                    // 严格交集（防幻觉/诱导的任意 URL 下载），空数组视为误传明确报错
+                    let targets = extracted;
+                    const rejections = [];
+                    if (args.image_urls !== undefined) {
+                        if (!Array.isArray(args.image_urls) || args.image_urls.length === 0) {
+                            throw new Error('image_urls 为空数组：如需下载全部请省略该参数，如需指定请传入 view 返回清单中的 URL。');
+                        }
+                        const filtered = filterRequestedUrls(args.image_urls, extracted);
+                        targets = filtered.matched;
+                        for (const bad of filtered.rejected) {
+                            rejections.push(`${String(bad).slice(-24)}: 不在本 Issue 图片清单中，已拒绝（防任意下载）`);
+                        }
+                    }
+                    // 第三步：共享下载执行体（gh api 二进制通道 + 魔数校验 + 字节护栏 + 内容寻址落盘）
+                    const { images, failures: dlFailures, remaining } = await downloadImages(targets, (url) => executor.run(['api', url], { ...runOpts, binary: true, timeoutMs: 30_000 }));
+                    const failures = [...rejections, ...dlFailures];
+                    if (images.length === 0 && rejections.length === 0 && !remaining) {
+                        return { message: `Issue #${args.issue_number} 的图片全部下载失败：`, failures };
+                    }
+                    if (images.length === 0) {
+                        return { message: `Issue #${args.issue_number} 未能获取任何图片（请求 ${targets.length} 张，被拒 ${rejections.length} 张）`, failures, remaining };
+                    }
+                    return {
+                        message: `Issue #${args.issue_number} 成功获取 ${images.length} 张图片${failures.length ? `（${failures.length} 条失败/提示）` : ''}：`,
+                        images,
+                        failures: failures.length ? failures : undefined,
+                        // 续传清单：触顶时 Agent 直接 image_urls: remaining 发起下一批
+                        remaining,
+                    };
                 }
                 case 'create': {
                     const cmd = ['issue', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
@@ -105,6 +212,39 @@ export function createIssueTool(executor) {
                         throw new Error(res.error);
                     return { message: 'Issue 创建成功', url: res.rawOutput };
                 }
+                case 'edit': {
+                    if (!args.issue_number)
+                        throw new Error('edit 操作必须提供 issue_number');
+                    const editCmd = ['issue', 'edit', String(args.issue_number), ...repoArgs];
+                    if (args.title)
+                        editCmd.push('--title', args.title);
+                    if (args.body)
+                        editCmd.push('--body', args.body);
+                    if (args.add_labels && Array.isArray(args.add_labels) && args.add_labels.length > 0) {
+                        for (const l of args.add_labels)
+                            editCmd.push('--add-label', l);
+                    }
+                    if (args.remove_labels && Array.isArray(args.remove_labels) && args.remove_labels.length > 0) {
+                        for (const l of args.remove_labels)
+                            editCmd.push('--remove-label', l);
+                    }
+                    const res = await executor.run(editCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Issue #${args.issue_number} 更新成功`, output: res.rawOutput };
+                }
+                case 'develop': {
+                    if (!args.issue_number)
+                        throw new Error('develop 操作必须提供 issue_number');
+                    const devCmd = ['issue', 'develop', String(args.issue_number), ...repoArgs, '--checkout'];
+                    if (args.branch_name) {
+                        devCmd.push('-n', args.branch_name);
+                    }
+                    const res = await executor.run(devCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `已成功为 Issue #${args.issue_number} 创建并检出开发分支`, output: res.rawOutput };
+                }
                 case 'comment': {
                     if (!args.issue_number || !args.body)
                         throw new Error('comment 必须提供 issue_number 和 body');
@@ -116,6 +256,14 @@ export function createIssueTool(executor) {
                 case 'close': {
                     if (!args.issue_number)
                         throw new Error('close 操作必须提供 issue_number');
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将关闭 Issue #${args.issue_number}。`,
+                            impact: '关闭后该议题状态将变更为 CLOSED，请与用户确认是否确实已解决或需要关闭。',
+                            requiredAction: '如确认关闭，请在参数中附加 `confirm: true` 重新调用。',
+                        };
+                    }
                     const res = await executor.run(['issue', 'close', String(args.issue_number), ...repoArgs], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);

package/lib/tools/pr.d.ts

@@ -52,10 +52,38 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            state: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            author: {
+                type: string;
+                description: string;
+            };
+            stat_only: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
             dry_run: {
                 type: string;
                 description: string;
             };
+            image_urls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: string[];
     };
@@ -63,10 +91,7 @@ export declare function createPrTool(executor: GhExecutor): {
         schema: {
             type: string;
         };
-        render(args: any, value: any): {
-            type: string;
-            text: any;
-        }[];
+        render(args: any, value: any): any[];
     };
     execute(args: any, execContext: any): Promise<Record<string, any>>;
 };

package/lib/tools/pr.js

@@ -1,3 +1,5 @@
+import { renderPrMarkdown } from '../renderers/markdown.js';
+import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -10,18 +12,18 @@ function normalizeOutput(data) {
 export function createPrTool(executor) {
     return {
         name: 'github_pr',
-        description: '管理与审查 GitHub Pull Request (PR)。支持查看列表、详情、差异比对、CI 检查状态、代码审查与合并操作。默认针对当前工作区关联的仓库。',
+        description: '管理与审查 GitHub Pull Request (PR)。支持查看列表、详情、差异比对、CI 检查状态、代码审查、合并操作、本地代码检出 (checkout) 与冲突状态检测 (status)。默认针对当前工作区关联的仓库。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge'],
-                    description: 'PR 操作类型。',
+                    enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status', 'view_images'],
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片（UI 变更对比图、复现截图等）到本地并以图片内容块返回，供 Agent 审查时直接查看。',
                 },
                 pr_number: {
                     type: 'number',
-                    description: 'PR 编号（view, diff, checks, review, merge 时使用；若在 PR 对应分支可不填，自动识别当前分支 PR）。',
+                    description: 'PR 编号（view, diff, checks, review, merge, checkout 时使用；若在 PR 对应分支可不填，自动识别当前分支 PR）。',
                 },
                 repo: {
                     type: 'string',
@@ -61,25 +63,43 @@ export function createPrTool(executor) {
                     type: 'boolean',
                     description: '合并后是否删除源分支（merge 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
                 },
+                state: {
+                    type: 'string',
+                    enum: ['open', 'closed', 'merged', 'all'],
+                    description: 'PR 状态过滤（list 操作时使用，可选 open, closed, merged, all，默认 open）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回 PR 数量上限（list 操作时使用，默认 20，建议最大不超过 100）。',
+                },
+                author: {
+                    type: 'string',
+                    description: '按作者筛选（list 动作使用，支持 "@me" 或 GitHub 用户名）。',
+                },
+                stat_only: {
+                    type: 'boolean',
+                    description: '是否仅输出文件变动概览（diff 动作使用，映射为 gh pr diff --stat，防止大 PR 爆 Token）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（merge 动作或 delete_branch 时必需）。若为 false 则仅输出合并预演警告。',
+                },
                 dry_run: {
                     type: 'boolean',
                     description: '是否只预演不真正创建（create 操作时使用，默认 false）。透传 gh --dry-run：打印将要创建的 PR 详情而不落库，用于提交前确认 head/base/title 是否正确。',
                 },
+                image_urls: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'view_images 可选：仅下载指定 URL 的图片（从 view 返回的 images 清单中选取，不在清单内的会被拒绝）。留空下载全部（正文+评论）。',
+                },
             },
             required: ['action'],
         },
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                if (!value)
-                    return [{ type: 'text', text: '无返回内容' }];
-                if (typeof value.result === 'string') {
-                    return [{ type: 'text', text: value.result }];
-                }
-                if (Array.isArray(value.items)) {
-                    return [{ type: 'text', text: JSON.stringify(value.items, null, 2) }];
-                }
-                return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+                return [{ type: 'text', text: renderPrMarkdown(args, value) }, ...buildImageBlocks(value)];
             },
         },
         async execute(args, execContext) {
@@ -99,32 +119,130 @@ export function createPrTool(executor) {
             const runOpts = { cwd, sessionId };
             switch (args.action) {
                 case 'list': {
-                    const res = await executor.run(['pr', 'list', ...repoArgs, '--json', 'number,title,author,headRefName,isDraft,state,updatedAt', '-L', '20'], runOpts);
+                    const listCmd = ['pr', 'list', ...repoArgs, '--json', 'number,title,author,headRefName,isDraft,state,updatedAt,mergedAt,url'];
+                    if (args.state) {
+                        listCmd.push('--state', args.state);
+                    }
+                    if (args.author) {
+                        listCmd.push('--author', args.author);
+                    }
+                    // 显式 limit 优先；缺省回退 executor.defaultListLimit（用户可在插件配置中调整）
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : Math.min(executor.defaultListLimit ?? 20, 100);
+                    listCmd.push('-L', String(limit));
+                    const res = await executor.run(listCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
                 case 'view': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url'], runOpts);
+                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url,comments'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
-                    return normalizeOutput(res.data || res.rawOutput);
+                    const out = normalizeOutput(res.data || res.rawOutput);
+                    // 附带图片 URL 清单（正文+评论，与 view_images 提取范围同源）：
+                    // Agent 按正文里的原始 URL 决策，需要看图时用 image_urls 精准选取
+                    const bodies = [typeof out.body === 'string' ? out.body : ''];
+                    if (Array.isArray(out.comments)) {
+                        for (const c of out.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    out.images = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    return out;
+                }
+                case 'view_images': {
+                    if (!args.pr_number)
+                        throw new Error('view_images 操作必须提供 pr_number');
+                    // PR 与 Issue 图片机制同构；评论走同一 issues-comments API（实测 PR 评论
+                    // 的 <img> 形态与 issue 完全一致），正文 + 评论合并提取一次覆盖全部
+                    const detail = await executor.run(['pr', 'view', String(args.pr_number), ...repoArgs, '--json', 'body,comments'], runOpts);
+                    if (!detail.ok)
+                        throw new Error(detail.error);
+                    const d = detail.data && typeof detail.data === 'object' ? detail.data : {};
+                    const bodies = [];
+                    if (typeof d.body === 'string')
+                        bodies.push(d.body);
+                    if (Array.isArray(d.comments)) {
+                        for (const c of d.comments) {
+                            if (c && typeof c.body === 'string')
+                                bodies.push(c.body);
+                        }
+                    }
+                    // 多来源合并去重（Set 语义由 extractImageUrls 内部保证）
+                    const extracted = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    if (extracted.length === 0) {
+                        return { message: `PR #${args.pr_number} 正文与评论中未发现图片附件。` };
+                    }
+                    // 目标选择：不传 image_urls 下载全部；传入则与清单严格交集
+                    //（防幻觉/诱导的任意 URL 下载），空数组视为误传明确报错
+                    let targets = extracted;
+                    const rejections = [];
+                    if (args.image_urls !== undefined) {
+                        if (!Array.isArray(args.image_urls) || args.image_urls.length === 0) {
+                            throw new Error('image_urls 为空数组：如需下载全部请省略该参数，如需指定请传入 view 返回清单中的 URL。');
+                        }
+                        const filtered = filterRequestedUrls(args.image_urls, extracted);
+                        targets = filtered.matched;
+                        for (const bad of filtered.rejected) {
+                            rejections.push(`${String(bad).slice(-24)}: 不在本 PR 图片清单中，已拒绝（防任意下载）`);
+                        }
+                    }
+                    const { images, failures: dlFailures, remaining } = await downloadImages(targets, (url) => executor.run(['api', url], { ...runOpts, binary: true, timeoutMs: 30_000 }));
+                    const failures = [...rejections, ...dlFailures];
+                    if (images.length === 0 && rejections.length === 0 && !remaining) {
+                        return { message: `PR #${args.pr_number} 的图片全部下载失败：`, failures };
+                    }
+                    if (images.length === 0) {
+                        return { message: `PR #${args.pr_number} 未能获取任何图片（请求 ${targets.length} 张，被拒 ${rejections.length} 张）`, failures, remaining };
+                    }
+                    return {
+                        message: `PR #${args.pr_number} 成功获取 ${images.length} 张图片（正文+评论）${failures.length ? `（${failures.length} 条失败/提示）` : ''}：`,
+                        images,
+                        failures: failures.length ? failures : undefined,
+                        // 续传清单：触顶时 Agent 直接 image_urls: remaining 发起下一批
+                        remaining,
+                    };
                 }
                 case 'checks': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'checks', ...target, ...repoArgs, '--json', 'name,state,conclusion,detailsUrl'], runOpts);
+                    // 字段集为 gh pr checks 的合法九字段子集（v2.50.0 引入 --json 起从未变更）。
+                    // 旧字段集的 conclusion/detailsUrl 是 REST API 字段名，pr checks 从未支持——
+                    // 初版误搬导致该 action 在所有 gh 版本上必然报 Unknown JSON field（Issue #3）。
+                    // bucket 是 state 的分类视图（pass/fail/pending/skipping/cancel），link 即详情页。
+                    const res = await executor.run(['pr', 'checks', ...target, ...repoArgs, '--json', 'name,state,bucket,link,workflow,startedAt,completedAt'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
                 case 'diff': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'diff', ...target, ...repoArgs], runOpts);
+                    const diffCmd = ['pr', 'diff', ...target, ...repoArgs];
+                    if (args.stat_only === true) {
+                        diffCmd.push('--stat');
+                    }
+                    const res = await executor.run(diffCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return { result: res.rawOutput || '无差异内容' };
                 }
+                case 'checkout': {
+                    if (!args.pr_number)
+                        throw new Error('checkout 操作必须提供 pr_number');
+                    const checkoutCmd = ['pr', 'checkout', String(args.pr_number), ...repoArgs, '-f'];
+                    const res = await executor.run(checkoutCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `已成功将 PR #${args.pr_number} 检出至本地分支`, output: res.rawOutput || 'Checked out' };
+                }
+                case 'status': {
+                    const statusCmd = ['pr', 'status', ...repoArgs, '-c', '--json', 'number,title,state,mergeStateStatus,url'];
+                    const res = await executor.run(statusCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
                 case 'create': {
                     const createCmd = ['pr', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
                     if (args.base)
@@ -166,6 +284,14 @@ export function createPrTool(executor) {
                 case 'merge': {
                     if (!args.pr_number)
                         throw new Error('merge 操作必须提供 pr_number');
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将合并 PR #${args.pr_number}（合并策略: ${args.merge_method || 'squash'}${args.delete_branch ? '，且删除源分支' : ''}）。`,
+                            impact: '合并操作将直接向基准分支写入代码并更新远端 PR 状态。',
+                            requiredAction: '如确认执行合并，请向用户明确确认并附加 `confirm: true` 重新调用。',
+                        };
+                    }
                     const method = args.merge_method === 'merge' ? '--merge' : (args.merge_method === 'rebase' ? '--rebase' : '--squash');
                     const mergeCmd = ['pr', 'merge', String(args.pr_number), ...repoArgs, method];
                     // 删分支默认关闭：合并他人仓库的 PR 时删掉源分支是不可撤销的破坏性动作，

package/lib/tools/release.d.ts

@@ -0,0 +1,89 @@
+import type { GhExecutor } from '../executor.js';
+export declare function createReleaseTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            tag: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            notes: {
+                type: string;
+                description: string;
+            };
+            generate_notes: {
+                type: string;
+                description: string;
+            };
+            draft: {
+                type: string;
+                description: string;
+            };
+            prerelease: {
+                type: string;
+                description: string;
+            };
+            target: {
+                type: string;
+                description: string;
+            };
+            assets: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            clobber: {
+                type: string;
+                description: string;
+            };
+            pattern: {
+                type: string;
+                description: string;
+            };
+            dir: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+            cleanup_tag: {
+                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>>;
+};