dsh-github-flow 0.1.8 → 0.2.0

package/lib/tools/help.js

@@ -0,0 +1,212 @@
+const KNOWLEDGE_BASE = {
+    overview: `### 🧭 DSH GitHub Flow 工具箱全景导航
+
+本插件提供面向 DeepSeek Harness 的原生 GitHub 协作与智能体基础设施工具矩阵：
+
+| 工具名称 | 核心职责 | 典型调用场景 |
+| :--- | :--- | :--- |
+| \`github_pr\` | Pull Request 管理、审查与本地检出 | 查看 PR 列表/详情、比对 diff、本地检出代码验证、检查 CI 状态、执行带确认合并 |
+| \`github_issue\` | Issue 任务追踪与分支开发关联 | 筛选待办议题、追加评论、编辑标题/标签、从 Issue 一键切出关联开发分支 |
+| \`github_run\` | GitHub Actions 构建排查与工作流管理 | 查看构建列表、提取失败日志 (log_failed)、重新触发、手动触发 workflow_dispatch |
+| \`github_repo\` | 仓库元数据、Fork 同步与全局检索 | 查看仓库与 topics、一键拉平 Fork 仓库 (sync)、检索全局代码与仓库 |
+| \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
+| \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
+| \`github_secret\` | CI/CD 部署密钥安全管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥 |
+| \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
+| \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
+
+💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。`,
+    pr: `### 🔀 github_pr 详细操作指南
+
+- **查看列表**: \`github_pr(action: 'list', state: 'open' | 'closed' | 'merged' | 'all', limit: 20, author: '@me')\`
+- **本地检出代码**: \`github_pr(action: 'checkout', pr_number: 123)\`
+  - 自动切换到本地分支并拉取最新提交，非常适用于 Agent 在本地沙箱中跑单元测试验证 PR 改动。
+- **差异比对**: \`github_pr(action: 'diff', pr_number: 123, stat_only: true)\`
+  - 对于大 PR，强烈建议先开启 \`stat_only: true\` 查看改动文件概览，防止超大 diff 触发截断或撑爆上下文。
+- **检查冲突状态**: \`github_pr(action: 'status')\`
+  - 查看当前分支关联 PR 的 merge conflict 状态。
+- **安全合并**: \`github_pr(action: 'merge', pr_number: 123, confirm: true, merge_method: 'squash', delete_branch: false)\`
+  - 高危操作必须显式附带 \`confirm: true\`；若未传将返回拦截警告与待合并影响报告。`,
+    issue: `### 🎯 github_issue 详细操作指南
+
+- **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
+- **关联开发分支**: \`github_issue(action: 'develop', issue_number: 42, branch_name: 'fix-login-bug')\`
+  - 自动在远端和本地创建带有官方关联关系的开发分支并切换过去，实现“读需求 -> 开分支写代码”的无缝衔接。
+- **编辑 Issue**: \`github_issue(action: 'edit', issue_number: 42, title: '新标题', add_labels: ['p1'], remove_labels: ['triage'])\`
+- **追加讨论**: \`github_issue(action: 'comment', issue_number: 42, body: '定位到问题原因...')\`
+- **安全关闭**: \`github_issue(action: 'close', issue_number: 42, confirm: true)\`
+  - 关闭操作必须附带 \`confirm: true\`。`,
+    run: `### 🚀 github_run 详细操作指南
+
+- **过滤构建记录**: \`github_run(action: 'list', branch: 'main', status: 'failure', limit: 10)\`
+  - 快速定位失败的 CI 构建，排查报错首选 \`status: 'failure'\`。
+- **提取失败步骤日志**: \`github_run(action: 'log_failed', run_id: '12345678')\`
+  - 专为 Agent 优化的失败信息提取能力，直接定位报错位置；若无失败步骤则优雅提示。
+- **主动触发工作流**: \`github_run(action: 'trigger', workflow: 'pr-check.yml', ref: 'main', inputs: { env: 'staging' })\`
+  - 提交代码修复后，主动触发远端 CI/CD 验证。
+- **重新执行失败任务**: \`github_run(action: 'rerun', run_id: '12345678')\``,
+    repo: `### 📦 github_repo 详细操作指南
+
+- **查看元数据与标签**: \`github_repo(action: 'view')\`
+  - 返回仓库基本信息、默认分支、Star 计数、许可证以及 \`repositoryTopics\`（用于 DSH 插件合规审查）。
+- **一键拉平 Fork 主干 (防止 Stale)**: \`github_repo(action: 'sync', branch: 'main')\`
+  - 解决开源项目贡献中因本地 Fork 落后导致上游 CI 门禁失败的顽疾。
+- **代码检索**: \`github_repo(action: 'search_code', query: 'filename:package.json dsh.bundle')\``,
+    api: `### ⚡ github_api 底层逃生门指南
+
+- **标准 GET 请求带参数**:
+  \`github_api(endpoint: 'repos/owner/repo/pulls', fields: { state: 'closed', per_page: 5 })\`
+  - 插件会自动追加 \`-X GET\`，将 fields 作为 URL Query String 传递，杜绝被 gh 自动改写为 POST。
+- **读取仓库原始文件字节**:
+  \`github_api(endpoint: 'repos/owner/repo/contents/path/to/file.yml', raw: true)\`
+  - 附加 \`Accept: application/vnd.github.raw\`，返回纯文本而非 base64 包装。
+- **全量聚合翻页**:
+  \`github_api(endpoint: 'repos/owner/repo/commits', paginate: true)\`
+- **GraphQL 请求**:
+  \`github_api(endpoint: 'graphql', fields: { query: 'query { viewer { login } }' })\``,
+    release: `### 🏷️ github_release 版本发布指南
+
+- **查看发版历史**: \`github_release(action: 'list', limit: 10)\`
+- **查看某个版本详情**: \`github_release(action: 'view', tag: 'v0.1.9')\`（留空 tag 查看最新）
+- **创建 Release（自动生成说明）**:
+  \`github_release(action: 'create', tag: 'v0.1.9', generate_notes: true, prerelease: false)\`
+  - 若远端尚无该 Tag，gh 会自动从 target 分支（默认主分支）最新提交打 Tag。
+- **上传构建资产**:
+  \`github_release(action: 'upload', tag: 'v0.1.9', assets: ['./dsh-github-flow-0.1.9.tgz'])\`
+  - 覆盖同名旧资产必须附加 \`clobber: true, confirm: true\`（旧资产删除后不可恢复）。
+- **下载资产**: \`github_release(action: 'download', tag: 'v0.1.9', pattern: '*.tgz', dir: './dist')\`
+- **删除 Release**: \`github_release(action: 'delete', tag: 'v0.1.9', confirm: true)\`
+  - 高危不可逆操作，必须显式确认。`,
+    secret: `### 🔐 github_secret 部署密钥管理指南
+
+- **查看密钥清单**: \`github_secret(action: 'list')\`
+  - 仅返回名称、可见性与更新时间；GitHub API 设计上就不允许读取密文。
+- **设置/更新密钥（安全通道）**:
+  \`github_secret(action: 'set', name: 'NPM_TOKEN', value: 'npm_xxxx')\`
+  - 密文经子进程标准输入传递，绝不出现在命令行参数（防 ps 窃取），输出永不回显。
+  - gh 在本地用仓库公钥加密后才上传，明文不落盘。
+- **组织/环境级密钥**: 附加 \`org: 'my-org'\` 或 \`env: 'production'\` 参数切换作用域。
+- **删除密钥**: \`github_secret(action: 'delete', name: 'NPM_TOKEN', confirm: true)\`
+  - 删除后引用该密钥的 CI 工作流会立即失败，务必先确认无工作流依赖。`,
+    skill: `### 🧠 github_skill Agent Skills 生态指南
+
+基于 GitHub CLI 的 \`gh skill\` preview 特性（需 gh >= 2.9x），跨仓库发现与安装开源 Agent Skills：
+
+- **检索 Skills**: \`github_skill(action: 'search', query: 'code-review', limit: 15)\`
+  - 可附加 \`owner: 'github'\` 限定作者组织。
+- **预览 Skill 内容**: \`github_skill(action: 'preview', repository: 'github/awesome-copilot', skill_name: 'code-review')\`
+  - 只读不落盘，适合安装前审阅 SKILL.md 行为约束。
+- **安装 Skill**:
+  \`github_skill(action: 'install', repository: 'github/awesome-copilot', skill_name: 'code-review', agent: 'claude-code', scope: 'project', confirm: true)\`
+  - install 会写本地磁盘，必须 \`confirm: true\`；scope 默认 project（当前 git 仓库）。
+  - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
+- **查看已安装**: \`github_skill(action: 'list')\`
+- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+    search_syntax: `### 🔍 GitHub 官方高级检索语法速查手册
+
+在 \`github_repo\`、\`github_api\` 或搜索场景中，请严格遵守 GitHub 官方搜索语法：
+
+1. **日期区间语法 (严格使用两点 .. 表示)**:
+   - \`created:2026-10-01..2026-10-12\`（2026年10月1日到10月12日之间）
+   - \`created:>2026-10-01\` 或 \`created:<2026-10-12\`
+   - ⚠️ **禁忌**：GitHub 搜索**不支持**数字范围 \`6129..6695\`，这会导致静默返回 0 条结果。
+2. **状态与类型修饰符**:
+   - \`is:pr\`、\`is:issue\`、\`is:open\`、\`is:closed\`、\`is:merged\`、\`is:draft\`
+3. **关联者修饰符**:
+   - \`author:@me\`、\`author:username\`、\`assignee:@me\`、\`mentions:username\`
+4. **CI 状态修饰符**:
+   - \`status:success\`、\`status:failure\`、\`status:pending\`
+5. **代码搜索范围限制**:
+   - \`repo:owner/repo\`、\`path:src/\`、\`filename:package.json\`、\`extension:ts\``,
+    troubleshooting: `### 🛠️ 常见故障诊断与自愈配方
+
+1. **报 \`HTTP 422: "base", "head" weren't supplied\`**:
+   - *原因*：使用 gh api 传递参数时缺少 \`-X GET\`，导致 gh 隐式将其视作 POST 新建 PR 请求。
+   - *解法*：本插件已在底层自动补全 \`-X GET\`；若使用原始端点，确保直接将参数拼接在 URL query 或传递 method: 'GET'。
+2. **报 \`HTTP 403: API rate limit exceeded\`**:
+   - *原因*：GitHub 账号 API 配额耗尽或短时间内突发高并发被二级风控。
+   - *解法*：等待当前小时重置，或减少无意义的循环轮询；使用高层工具的针对性过滤条件减少请求次数。
+3. **报 \`Submission gate: stale fork\` 或上游门禁失败**:
+   - *原因*：Fork 的仓库落后于主干，合并时带入了过期的配置或删除了近期条目。
+   - *解法*：调用 \`github_repo(action: 'sync')\` 自动对齐 upstream 主干代码。
+4. **报 \`System cannot find GitHub CLI (gh)\`**:
+   - *解法*：宿主机尚未安装 gh。Windows 运行 \`winget install GitHub.cli\`，macOS 运行 \`brew install gh\`，然后执行 \`gh auth login\` 登录。
+ 5. **报 \`unknown command "skill" for "gh"\`**:
+    - *原因*：\`gh skill\` 是 GitHub CLI 2.9x 引入的 preview 特性，宿主机版本过低。
+    - *解法*：升级 gh（Windows: \`winget upgrade GitHub.cli\`；macOS: \`brew upgrade gh\`）后重试；升级前可改用 \`github_api\` 检索 \`SKILL.md\` 文件路径作为替代。`
+};
+export function createHelpTool(executor) {
+    return {
+        name: 'github_help',
+        description: 'GitHub 工具箱使用指南与官方命令手册。当你不确定该用哪个工具、需要特定操作的高级语法与示例、或排查 GitHub 报错时调用。',
+        parameters: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    enum: [
+                        'overview',
+                        'pr',
+                        'issue',
+                        'run',
+                        'repo',
+                        'api',
+                        'release',
+                        'secret',
+                        'skill',
+                        'search_syntax',
+                        'troubleshooting',
+                    ],
+                    description: '帮助主题分类。留空则返回全局工具箱导航。',
+                },
+                gh_command: {
+                    type: 'string',
+                    description: '可选：直接查询 GitHub CLI 官方原始命令帮助手册（例如 "pr create"、"search code"、"ruleset"）。',
+                },
+            },
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                if (!value)
+                    return [{ type: 'text', text: '无返回内容' }];
+                if (typeof value.result === 'string') {
+                    return [{ type: 'text', text: value.result }];
+                }
+                return [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // 1. 若显式指定了 gh_command，直接透传查询官方离线手册
+            if (args.gh_command && typeof args.gh_command === 'string') {
+                let parts = args.gh_command.trim().split(/\s+/);
+                // 容错调用方输入 "gh pr create" 带有前导 "gh" 的情形
+                if (parts[0] === 'gh') {
+                    parts.shift();
+                }
+                const res = await executor.run(['help', ...parts], { cwd, sessionId, rawText: true });
+                if (!res.ok) {
+                    return {
+                        result: `未找到命令「gh ${args.gh_command}」的官方帮助手册：${res.error}\n建议通过 topic 参数查询内置指南。`,
+                    };
+                }
+                return { result: res.rawOutput };
+            }
+            // 2. 查询内置知识库速查表
+            // 类型防护：DSH 网关对 enum 参数的拦截强度依赖实现，Agent 仍可能传非字符串
+            // （数字/对象/数组）。`-1 || 'overview'` 真值短路挡不住负数，会炸 toLowerCase。
+            // 与上方 gh_command 分支的 typeof 防护保持同一强度。
+            const rawTopic = typeof args.topic === 'string' && args.topic.trim() ? args.topic : 'overview';
+            const topic = rawTopic.toLowerCase().trim();
+            const content = KNOWLEDGE_BASE[topic];
+            if (content) {
+                return { result: content };
+            }
+            return {
+                result: `未找到主题「${rawTopic}」的指南。可用主题：${Object.keys(KNOWLEDGE_BASE).join(', ')}。`,
+            };
+        },
+    };
+}

package/lib/tools/issue.d.ts

@@ -40,6 +40,37 @@ export declare function createIssueTool(executor: GhExecutor): {
                 };
                 description: string;
             };
+            state: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            branch_name: {
+                type: string;
+                description: string;
+            };
+            add_labels: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            remove_labels: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
@@ -49,7 +80,7 @@ export declare function createIssueTool(executor: GhExecutor): {
         };
         render(args: any, value: any): {
             type: string;
-            text: any;
+            text: string;
         }[];
     };
     execute(args: any, execContext: any): Promise<Record<string, any>>;

package/lib/tools/issue.js

@@ -1,3 +1,4 @@
+import { renderIssueMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -10,18 +11,18 @@ function normalizeOutput(data) {
 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'],
+                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop'],
                     description: 'Issue 操作类型。',
                 },
                 issue_number: {
                     type: 'number',
-                    description: 'Issue 编号（view, comment, close, reopen 时使用）。',
+                    description: 'Issue 编号（view, comment, close, reopen, edit, develop 时使用）。',
                 },
                 repo: {
                     type: 'string',
@@ -29,21 +30,48 @@ 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 则仅输出待关闭警告。',
                 },
             },
             required: ['action'],
@@ -51,15 +79,7 @@ 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) }];
+                return [{ type: 'text', text: renderIssueMarkdown(args, value) }];
             },
         },
         async execute(args, execContext) {
@@ -79,7 +99,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);
@@ -105,6 +141,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 +185,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,6 +52,27 @@ 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;
@@ -65,7 +86,7 @@ export declare function createPrTool(executor: GhExecutor): {
         };
         render(args: any, value: any): {
             type: string;
-            text: any;
+            text: string;
         }[];
     };
     execute(args: any, execContext: any): Promise<Record<string, any>>;

package/lib/tools/pr.js

@@ -1,3 +1,4 @@
+import { renderPrMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -10,18 +11,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'],
+                    description: 'PR 操作类型。新增 checkout (检出 PR 到本地分支)、status (检测当前分支 PR 冲突与状态)。',
                 },
                 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,6 +62,27 @@ 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 是否正确。',
@@ -71,15 +93,7 @@ export function createPrTool(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) }];
+                return [{ type: 'text', text: renderPrMarkdown(args, value) }];
             },
         },
         async execute(args, execContext) {
@@ -99,7 +113,17 @@ 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);
@@ -120,11 +144,31 @@ export function createPrTool(executor) {
                 }
                 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 +210,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 时删掉源分支是不可撤销的破坏性动作，