dsh-github-flow 0.2.1 → 0.3.0

package/lib/renderers/markdown.js

@@ -73,6 +73,17 @@ export function formatConflictBadge(status) {
         return '⛔ BLOCKED';
     return s;
 }
+/**
+ * 降级链路可见标注（runGuarded 契约的渲染兑现）。
+ * 为什么必须可见：降级若是静默的，Agent 就无法感知能力边界（同一 action 在
+ * 不同 gh 版本上走不同链路）；一条 blockquote 注释成本一行，换链路透明。
+ */
+export function appendDegradedNote(value) {
+    if (value && value.degraded === true && value.degradedReason) {
+        return `\n\n> ⚠️ ${value.degradedReason}`;
+    }
+    return '';
+}
 // -------------------------------------------------------------
 // 1. PR 渲染器
 // -------------------------------------------------------------
@@ -280,7 +291,34 @@ export function renderRunMarkdown(args, value) {
             ...rows,
         ].join('\n');
     }
-    // 3.2 Run View 详情
+    // 3.2 Workflow 清单（字段集为 gh 2.96 实测合法全集 4 个）
+    if (Array.isArray(value.items) && args?.action === 'workflow_list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return args?.all === true ? '📭 该仓库没有任何工作流。' : '📭 暂无 active 工作流（可能全部 disabled，传 all: true 查看）。';
+        const rows = list.map((w) => {
+            const badge = w.state === 'active' ? '🟢 active' : (w.state === 'disabled' ? '🔴 disabled' : String(w.state || '-'));
+            return `| \`${w.id}\` | ${sanitizeCell(w.name, 40)} | ${badge} | \`${sanitizeCell(w.path, 45)}\` |`;
+        });
+        return [
+            `**工作流清单 (${list.length} 个${args?.all === true ? '，含 disabled' : ''}):**\n`,
+            '| ID | 名称 | 状态 | 文件 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 3.3 Workflow 详情（gh 无 --json，头部结构化 + Recent runs 原文引用块——D4 决策）
+    if (args?.action === 'workflow_view' && value.workflow) {
+        const lines = [
+            `### 🔄 ${value.workflow}`,
+            `- **ID**: \`${value.id || '-'}\`${value.totalRuns ? ` | **累计运行**: ${value.totalRuns} 次` : ''}`,
+        ];
+        if (value.recentRuns) {
+            lines.push('', '**最近运行:**', '```', value.recentRuns, '```');
+        }
+        return lines.join('\n');
+    }
+    // 3.4 Run View 详情
     if (args?.action === 'view' && value.databaseId) {
         const idLink = value.url ? `[${value.databaseId}](${value.url})` : `\`${value.databaseId}\``;
         const badge = formatCiBadge(value.status, value.conclusion);
@@ -330,7 +368,7 @@ export function renderRepoMarkdown(args, value) {
         const branch = value.defaultBranchRef?.name || value.defaultBranch || 'main';
         const lines = [
             `### 📦 ${link}`,
-            `> ⭐ **Stars**: ${stars} | 🍴 **Forks**: ${forks} | 🌿 **默认分支**: \`${branch}\``,
+            `> ⭐ **Stars**: ${stars} | 🍴 **Forks**: ${forks} | ⎇ **默认分支**: \`${branch}\``,
             value.description ? `\n${value.description}\n` : '',
         ];
         if (value.licenseInfo?.name || value.licenseInfo?.key) {
@@ -375,6 +413,75 @@ export function renderRepoMarkdown(args, value) {
             ...rows,
         ].join('\n');
     }
+    // 4.4 Issue/PR 搜索列表（search_issues / search_prs 共用，字段同构）
+    if (Array.isArray(value.items) && (args?.action === 'search_issues' || args?.action === 'search_prs')) {
+        if (value.items.length === 0)
+            return '未找到匹配的结果。';
+        const kind = args.action === 'search_prs' ? 'PR' : 'Issue';
+        const rows = value.items.map((it) => {
+            const num = it.number ?? '-';
+            const repo = it.repository?.nameWithOwner || it.repository?.fullName || '-';
+            const link = it.url ? `[#${num}](${it.url})` : `#${num}`;
+            const badge = formatStateBadge(it.state, it.isDraft);
+            const author = it.author?.login || '-';
+            const date = it.updatedAt ? String(it.updatedAt).slice(0, 10) : '-';
+            return `| ${link} | ${sanitizeCell(it.title, 45)} | ${badge} | ${repo} | ${author} | ${date} |`;
+        });
+        return [
+            `**${kind} 检索结果 (${value.items.length} 条):**\n`,
+            '| 编号 | 标题 | 状态 | 仓库 | 作者 | 更新日期 |',
+            '| :--- | :--- | :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.5 Commit 搜索列表（嵌套 commit.commit.message 取首行）
+    if (Array.isArray(value.items) && args?.action === 'search_commits') {
+        if (value.items.length === 0)
+            return '未找到匹配的提交。';
+        const rows = value.items.map((c) => {
+            const sha = `\`${String(c.sha || '').slice(0, 7)}\``;
+            const msg = sanitizeCell(String(c.commit?.message || '').split('\n')[0], 50);
+            const author = c.commit?.author?.name || c.author?.login || '-';
+            const repo = c.repository?.fullName || '-';
+            return `| ${sha} | ${msg} | ${author} | ${repo} |`;
+        });
+        return [
+            `**提交检索结果 (${value.items.length} 条):**\n`,
+            '| SHA | 提交信息 | 作者 | 仓库 |',
+            '| :--- | :--- | :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    // 4.6 目录清单（read_dir：dir 置顶 + size 人性化；mode 八进制是 Git 内部语义不展示）
+    if (args?.action === 'read_dir' && Array.isArray(value.items)) {
+        if (value.items.length === 0)
+            return `**${value.path || '/'}** 为空目录。` + appendDegradedNote(value);
+        const sorted = [...value.items].sort((a, b) => (a.type === b.type ? String(a.name).localeCompare(String(b.name)) : a.type === 'dir' ? -1 : 1));
+        const rows = sorted.map((e) => {
+            const icon = e.type === 'dir' ? '📁' : '📄';
+            const size = e.type === 'dir' ? '-' : (typeof e.size === 'number' ? (e.size > 1024 ? `${(e.size / 1024).toFixed(1)}KB` : `${e.size}B`) : '-');
+            return `| ${icon} \`${sanitizeCell(e.name, 60)}\` | ${size} |`;
+        });
+        return [
+            `**目录 ${value.path || '/'}（${value.items.length} 项）:**\n`,
+            '| 名称 | 大小 |',
+            '| :--- | :--- |',
+            ...rows,
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
+    // 4.7 文件内容（read_file：代码块 + 元信息行）
+    if (args?.action === 'read_file' && typeof value.content === 'string') {
+        const ext = (value.path || '').split('.').pop() || '';
+        const size = typeof value.size === 'number' ? (value.size > 1024 ? `${(value.size / 1024).toFixed(1)}KB` : `${value.size}B`) : '-';
+        return [
+            `**📄 \`${value.path}\`** (${size}${value.ref ? ` @ ${value.ref}` : ''})\n`,
+            '```' + ext,
+            value.content,
+            '```',
+            appendDegradedNote(value),
+        ].filter((l) => l !== '').join('\n');
+    }
     // 兜底降级
     return JSON.stringify(value, null, 2);
 }

package/lib/tools/help.js

@@ -7,15 +7,16 @@ const KNOWLEDGE_BASE = {
 | :--- | :--- | :--- |
 | \`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_run\` | Actions 构建排查与工作流管理 | 查看构建列表、提取失败日志 (log_failed)、重新触发、手动触发 workflow_dispatch、启停工作流、下载构建产物 |
+| \`github_repo\` | 仓库元数据、Fork 同步与全局检索 | 查看仓库与 topics、一键拉平 Fork (sync)、检索代码/仓库/Issue/PR/提交、免 clone 读取任意文件与目录 |
 | \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
 | \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
-| \`github_secret\` | CI/CD 部署密钥安全管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥 |
+| \`github_secret\` | CI/CD 密钥与变量管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥；kind:'variable' 管理明文变量（set/get/delete） |
 | \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
-💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。`,
+💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
 - **查看列表**: \`github_pr(action: 'list', state: 'open' | 'closed' | 'merged' | 'all', limit: 20, author: '@me')\`
@@ -29,7 +30,12 @@ const KNOWLEDGE_BASE = {
 - **检查冲突状态**: \`github_pr(action: 'status')\`
   - 查看当前分支关联 PR 的 merge conflict 状态。
 - **安全合并**: \`github_pr(action: 'merge', pr_number: 123, confirm: true, merge_method: 'squash', delete_branch: false)\`
-  - 高危操作必须显式附带 \`confirm: true\`；若未传将返回拦截警告与待合并影响报告。`,
+  - 高危操作必须显式附带 \`confirm: true\`；若未传将返回拦截警告与待合并影响报告。
+- **Draft 切换**: \`github_pr(action: 'ready', pr_number: 123)\`；反向转回 Draft 附加 \`undo: true\`
+- **反向提交**: \`github_pr(action: 'revert', pr_number: 123, confirm: true)\`
+  - 在远端创建反向提交与新 PR（非本地操作），需 confirm。
+- **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
+  - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。`,
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
@@ -44,7 +50,15 @@ const KNOWLEDGE_BASE = {
 - **编辑 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\`。`,
+  - 关闭操作必须附带 \`confirm: true\`。
+- **物理删除**: \`github_issue(action: 'delete', issue_number: 42, confirm: true)\`
+  - 与 close 有本质区别：编号永久消失、评论湮灭、GraphQL 层无法恢复——拦截级别高于 close。
+- **跨仓库迁移**: \`github_issue(action: 'transfer', issue_number: 42, target_repo: 'other/repo', confirm: true)\`
+  - 原 URL 301 重定向，归属改变不可静默撤回。
+- **置顶**: \`github_issue(action: 'pin'/'unpin', issue_number: 42)\`（可逆状态位）
+- **锁定对话**: \`github_issue(action: 'lock', issue_number: 42, lock_reason: 'resolved')\`
+  - reason 合法值：off_topic / resolved / spam / too_heated；解锁用 \`action: 'unlock'\`（独立命令）。
+- **我的分配议题**: \`github_issue(action: 'status')\`（账号维度面板）`,
     run: `### 🚀 github_run 详细操作指南
 
 - **过滤构建记录**: \`github_run(action: 'list', branch: 'main', status: 'failure', limit: 10)\`
@@ -53,7 +67,14 @@ const KNOWLEDGE_BASE = {
   - 专为 Agent 优化的失败信息提取能力，直接定位报错位置；若无失败步骤则优雅提示。
 - **主动触发工作流**: \`github_run(action: 'trigger', workflow: 'pr-check.yml', ref: 'main', inputs: { env: 'staging' })\`
   - 提交代码修复后，主动触发远端 CI/CD 验证。
-- **重新执行失败任务**: \`github_run(action: 'rerun', run_id: '12345678')\``,
+- **重新执行失败任务**: \`github_run(action: 'rerun', run_id: '12345678')\`
+- **工作流查询**: \`github_run(action: 'workflow_list', all: true)\`
+  - 默认仅 active；\`all: true\` 含 disabled（排查「工作流为何不跑」时 disabled 本身就是答案）。
+- **工作流详情**: \`github_run(action: 'workflow_view', workflow: 'npm-publish.yml')\`（名称/ID/文件名均可定位）
+- **启停工作流**: \`github_run(action: 'workflow_enable'/'workflow_disable', workflow: '…')\`
+  - disable 后 trigger 将静默失败，直至重新 enable——输出会显式警告这一点。
+- **下载构建产物**: \`github_run(action: 'download', run_id: '12345678', name: '构建产物名'?)\`
+  - 落盘目录由插件固定管理（\`~/.dsh/data/dsh-github-flow/artifacts/\` 下按仓库与 run 隔离），返回文件清单。`,
     repo: `### 📦 github_repo 详细操作指南
 
 - **查看元数据与标签**: \`github_repo(action: 'view')\`
@@ -63,7 +84,13 @@ const KNOWLEDGE_BASE = {
   - **下载图片查看**: 附加 \`image_urls: [...]\` 精准下载指定图（留空下载全部截图）；护栏与 Issue/PR 图片一致，触顶返回 remaining 可续传。
 - **一键拉平 Fork 主干 (防止 Stale)**: \`github_repo(action: 'sync', branch: 'main')\`
   - 解决开源项目贡献中因本地 Fork 落后导致上游 CI 门禁失败的顽疾。
-- **代码检索**: \`github_repo(action: 'search_code', query: 'filename:package.json dsh.bundle')\``,
+- **代码检索**: \`github_repo(action: 'search_code', query: 'filename:package.json dsh.bundle')\`
+- **Issue/PR/Commit 检索**: \`github_repo(action: 'search_issues'/'search_prs'/'search_commits', query: 'repo:o/r state:open')\`
+  - 限定符直接写进 query（gh 惯例）；注意 commits 必须含搜索文本，纯限定符会被 gh 拒绝。
+- **免 clone 读单文件**: \`github_repo(action: 'read_file', path: 'src/index.ts', ref: 'dev'?)\`
+  - gh ≥2.95 直连；低版本自动降级 contents API（输出带降级标注）。二进制文件会被拒绝并引导 github_api。
+- **免 clone 列目录**: \`github_repo(action: 'read_dir', path: '.github/workflows'?)\`
+  - 返回目录清单（dir 置顶 + 大小），降级链路同上。`,
     api: `### ⚡ github_api 底层逃生门指南
 
 - **标准 GET 请求带参数**:
@@ -89,7 +116,9 @@ const KNOWLEDGE_BASE = {
 - **下载资产**: \`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 部署密钥管理指南
+    secret: `### 🔐 github_secret 密钥与变量管理指南
+
+支持两类对象（kind 分流）：**Secret**（密文，默认）与 **Variable**（CI 明文变量）。
 
 - **查看密钥清单**: \`github_secret(action: 'list')\`
   - 仅返回名称、可见性与更新时间；GitHub API 设计上就不允许读取密文。
@@ -99,7 +128,11 @@ const KNOWLEDGE_BASE = {
   - gh 在本地用仓库公钥加密后才上传，明文不落盘。
 - **组织/环境级密钥**: 附加 \`org: 'my-org'\` 或 \`env: 'production'\` 参数切换作用域。
 - **删除密钥**: \`github_secret(action: 'delete', name: 'NPM_TOKEN', confirm: true)\`
-  - 删除后引用该密钥的 CI 工作流会立即失败，务必先确认无工作流依赖。`,
+  - 删除后引用该密钥的 CI 工作流会立即失败，务必先确认无工作流依赖。
+- **变量操作（CI 明文）**: 附加 \`kind: 'variable'\`
+  - \`github_secret(action: 'set', kind: 'variable', name: 'DEPLOY_ENV', value: 'staging')\`——经 -b 直传（明文无 stdin 红线）。
+  - \`github_secret(action: 'get', kind: 'variable', name: 'DEPLOY_ENV')\`——可回显值（这正是变量与密钥的设计区别：secret 写入后 GitHub 侧加密，物理不可读取）。
+  - list/delete 与 secret 同形（delete 需 confirm）。`,
     skill: `### 🧠 github_skill Agent Skills 生态指南
 
 基于 GitHub CLI 的 \`gh skill\` preview 特性（需 gh >= 2.9x），跨仓库发现与安装开源 Agent Skills：
@@ -114,6 +147,93 @@ const KNOWLEDGE_BASE = {
   - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
 - **查看已安装**: \`github_skill(action: 'list')\`
 - ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+    mapping: `### 🗺️ gh 命令 ↔ 插件工具映射总表
+
+#### 一、已覆盖域映射（语义化 action 精确对照）
+
+**PR（github_pr，13 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作 |
+| \`gh pr close\` | 暂无专用 action——用 \`github_pr(action:'edit')\` 或 \`github_api(endpoint:'repos/{o}/{r}/pulls/{n}', method:'PATCH', fields:{state:'closed'})\` | 插件侧未覆盖 |
+| \`gh pr checks\` | \`github_pr(action:'checks', pr_number:n)\` | CI 状态药丸 |
+| \`gh pr review\` | \`github_pr(action:'review', review_decision:'APPROVE'…)\` | |
+| \`gh pr merge\` | \`github_pr(action:'merge', confirm:true)\` | 高危确认 |
+| \`gh pr checkout\` | \`github_pr(action:'checkout')\` | 本地检出 |
+| \`gh pr status\` | \`github_pr(action:'status')\` | 当前分支关联 PR |
+| \`gh pr ready [--undo]\` | \`github_pr(action:'ready', undo:true?)\` | Draft↔Ready 可逆 |
+| \`gh pr revert\` | \`github_pr(action:'revert', confirm:true)\` | 远端创建反向 PR |
+| \`gh pr update-branch\` | \`github_pr(action:'update_branch')\` | 分支落后自愈 |
+
+**Issue（github_issue，16 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh issue list/view/create/comment/close/reopen/edit\` | \`github_issue(action:…)\` | 基础操作 |
+| \`gh issue develop\` | \`github_issue(action:'develop', branch_name:…)\` | 关联开发分支 |
+| \`gh issue delete\` | \`github_issue(action:'delete', confirm:true)\` | 物理删除（非 close） |
+| \`gh issue transfer\` | \`github_issue(action:'transfer', target_repo:…, confirm:true)\` | 跨仓库迁移 |
+| \`gh issue pin/unpin\` | \`github_issue(action:'pin'/'unpin')\` | 置顶状态位 |
+| \`gh issue lock/unlock\` | \`github_issue(action:'lock', lock_reason:'resolved'…)\` | reason 四枚举 |
+| \`gh issue status\` | \`github_issue(action:'status')\` | 我的分配议题面板 |
+
+**Actions（github_run，11 action）——注意 workflow 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh run list/view/rerun/cancel\` | \`github_run(action:…)\` | |
+| \`gh run view --log-failed\` | \`github_run(action:'log_failed', run_id:…)\` | 失败日志提取 |
+| \`gh run download\` | \`github_run(action:'download', run_id:…)\` | 落盘插件管理目录 |
+| \`gh workflow run\` | \`github_run(action:'trigger', workflow:…)\` | workflow_dispatch |
+| \`gh workflow list/view\` | \`github_run(action:'workflow_list'/'workflow_view')\` | all:true 含 disabled |
+| \`gh workflow enable/disable\` | \`github_run(action:'workflow_enable'/'workflow_disable')\` | disable 后 trigger 静默失败 |
+
+**Repo（github_repo，10 action）——注意 search 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh repo view\` | \`github_repo(action:'view')\` | 元数据 |
+| （README 读取，gh 无专用命令） | \`github_repo(action:'readme', repo:…)\` | 原文 + 图片清单/下载（插件独有） |
+| \`gh repo sync\` | \`github_repo(action:'sync', force:true?)\` | Fork 对齐 |
+| \`gh repo read-file\` | \`github_repo(action:'read_file', path:…)\` | 免 clone 读文件，gh<2.95 自动降级 API |
+| \`gh repo read-dir\` | \`github_repo(action:'read_dir', path:?)\` | 目录清单，同上降级 |
+| \`gh search code/repos\` | \`github_repo(action:'search_code'/'search_repos')\` | |
+| \`gh search issues/prs/commits\` | \`github_repo(action:'search_issues'/'search_prs'/'search_commits')\` | 限定符写进 query |
+
+**Release（github_release，6 action）**
+\`gh release list/view/create/upload/download/delete\` → \`github_release(action:…)\`；delete/clobber 需 confirm。
+
+**Secret 与 Variable（github_secret，kind 分流）——注意 variable 域也在此工具**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh secret list/set/delete\` | \`github_secret(action:…)\` | 密文走 stdin，永不回显 |
+| \`gh variable list/set/get/delete\` | \`github_secret(action:…, kind:'variable')\` | CI 明文：-b 直传、get 可回显 |
+| （gh secret get 不存在） | — | GitHub 侧加密存储，物理不可读取 |
+
+**Skill（github_skill，4 action）**
+\`gh skill search/preview/install/list\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）。
+
+#### 二、归属提示（命令域与工具名不同构）
+
+- \`gh workflow …\` / \`gh search …\` / \`gh variable …\` 分别归 **github_run / github_repo / github_secret**（不是独立工具）
+- \`gh api\` 的等价物是 \`github_api\`（全端点逃生门，支持 raw/paginate/jq）
+- 图片查看：\`github_issue\`/\`github_pr\` 的 \`view_images\`、\`github_repo\` 的 \`readme\` + image_urls（插件独有能力，gh 无对应命令）
+
+#### 三、未覆盖域引导（经 github_api 调用）
+
+| gh 域 | 用途 | 推荐 REST 端点 |
+| :--- | :--- | :--- |
+| \`gh label\` | 标签管理 | \`repos/{o}/{r}/labels\` |
+| \`gh cache\` | Actions 缓存 | \`repos/{o}/{r}/actions/caches\` |
+| \`gh gist\` | 代码片段 | \`gists\` |
+| \`gh ruleset\` | 分支保护规则 | \`repos/{o}/{r}/rulesets\` |
+| \`gh project\` | Projects v2 | \`graphql\`（Projects API 仅 GraphQL） |
+| \`gh discussion\` | 讨论 | \`graphql\`（需仓库开启 discussions） |
+| \`gh codespace\` | 云端开发环境 | \`user/codespaces\` |
+| \`gh org\` | 组织信息 | \`orgs/{org}\` |
+| \`gh auth/config/extension/alias\` | 本机配置类 | 多数无需 API（本机文件/命令） |
+| \`gh browse\` | 打开浏览器 | 直接给用户 URL 即可 |
+| \`gh attestation/gpg-key/ssh-key\` | 签名与密钥 | \`repos/{o}/{r}/attestations\` 等 |
+| \`gh agent-task\` | Copilot 会话 | \`graphql\`（需 Copilot 授权） |
+
+> 用法示例：\`github_api(endpoint: 'repos/owner/repo/labels', method: 'POST', fields: { name: 'bug', color: 'ff0000' })\``,
     search_syntax: `### 🔍 GitHub 官方高级检索语法速查手册
 
 在 \`github_repo\`、\`github_api\` 或搜索场景中，请严格遵守 GitHub 官方搜索语法：
@@ -166,10 +286,11 @@ export function createHelpTool(executor) {
                         'release',
                         'secret',
                         'skill',
+                        'mapping',
                         'search_syntax',
                         'troubleshooting',
                     ],
-                    description: '帮助主题分类。留空则返回全局工具箱导航。',
+                    description: '帮助主题分类。mapping 提供 gh 命令与插件工具的完整对照表（不确定某 gh 命令对应哪个工具时查询）。留空则返回全局工具箱导航。',
                 },
                 gh_command: {
                     type: 'string',

package/lib/tools/issue.d.ts

@@ -15,6 +15,15 @@ export declare function createIssueTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            target_repo: {
+                type: string;
+                description: string;
+            };
+            lock_reason: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             repo: {
                 type: string;
                 description: string;

package/lib/tools/issue.js

@@ -20,12 +20,21 @@ export function createIssueTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop', 'view_images'],
-                    description: 'Issue 操作类型。view_images 下载正文内的图片到本地并返回可渲染的图片内容块（Agent 可直接"看"用户报障截图）。',
+                    enum: ['list', 'view', 'create', 'comment', 'close', 'reopen', 'edit', 'develop', 'view_images', 'delete', 'transfer', 'pin', 'unpin', 'lock', 'unlock', 'status'],
+                    description: 'Issue 操作类型。view_images 下载正文内的图片到本地并返回可渲染的图片内容块（Agent 可直接"看"用户报障截图）。delete 物理删除不可恢复、transfer 跨仓库迁移，两者均需 confirm: true。',
                 },
                 issue_number: {
                     type: 'number',
-                    description: 'Issue 编号（view, comment, close, reopen, edit, develop 时使用）。',
+                    description: 'Issue 编号（view, comment, close, reopen, edit, develop, delete, transfer, pin/unpin/lock/unlock 时使用）。',
+                },
+                target_repo: {
+                    type: 'string',
+                    description: 'transfer 动作必填：迁移目标仓库 [owner/repo]（迁移后原 URL 301 重定向，归属不可静默撤回）。',
+                },
+                lock_reason: {
+                    type: 'string',
+                    enum: ['off_topic', 'resolved', 'spam', 'too_heated'],
+                    description: 'lock 动作可选：锁定原因（gh 实测四合法值）。',
                 },
                 repo: {
                     type: 'string',
@@ -74,7 +83,7 @@ export function createIssueTool(executor) {
                 },
                 confirm: {
                     type: 'boolean',
-                    description: '高危破坏性操作确认标志（close 动作必需）。若为 false 则仅输出待关闭警告。',
+                    description: '高危破坏性操作确认标志（close/delete/transfer 动作必需）。delete 物理删除不可恢复、transfer 跨仓库迁移，拦截级别高于 close。',
                 },
                 image_urls: {
                     type: 'array',
@@ -277,6 +286,81 @@ export function createIssueTool(executor) {
                         throw new Error(res.error);
                     return { message: `Issue #${args.issue_number} 已重新开启` };
                 }
+                // ---- 变更面新增（S3）----
+                case 'pin':
+                case 'unpin': {
+                    if (!args.issue_number)
+                        throw new Error(`${args.action} 操作必须提供 issue_number`);
+                    // 置顶状态位：可逆（pin↔unpin 互逆），按轻变更免 confirm
+                    const res = await executor.run(['issue', args.action, String(args.issue_number), ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Issue #${args.issue_number} 已${args.action === 'pin' ? '置顶' : '取消置顶'}` };
+                }
+                case 'lock':
+                case 'unlock': {
+                    if (!args.issue_number)
+                        throw new Error(`${args.action} 操作必须提供 issue_number`);
+                    // unlock 是 gh 独立命令（非 lock 的 flag，实测 help 已钉）；锁定对话可逆，免 confirm
+                    const cmd = ['issue', args.action, String(args.issue_number), ...repoArgs];
+                    if (args.action === 'lock' && args.lock_reason) {
+                        cmd.push('--reason', args.lock_reason);
+                    }
+                    const res = await executor.run(cmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        message: `Issue #${args.issue_number} 对话已${args.action === 'lock' ? '锁定' : '解锁'}`,
+                        ...(args.action === 'lock' && args.lock_reason ? { reason: args.lock_reason } : {}),
+                    };
+                }
+                case 'delete': {
+                    if (!args.issue_number)
+                        throw new Error('delete 操作必须提供 issue_number');
+                    // 物理删除 > close 的拦截级别：issue 编号永久消失、评论湮灭、GraphQL 无法恢复
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将**物理删除** Issue #${args.issue_number}（非 close，不可恢复）。`,
+                            impact: 'Issue 编号将永久消失，全部评论与附件随之湮灭，GraphQL 层无法恢复——这与 close（可 reopen 逆转）有本质区别。',
+                            requiredAction: '如确认删除，请与用户核实后附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    // 非 TTY 下 gh issue delete 会挂起等待 prompt，--yes 是非交互执行的唯一途径
+                    const res = await executor.run(['issue', 'delete', String(args.issue_number), ...repoArgs, '--yes'], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Issue #${args.issue_number} 已永久删除（不可恢复）` };
+                }
+                case 'transfer': {
+                    if (!args.issue_number)
+                        throw new Error('transfer 操作必须提供 issue_number');
+                    if (!args.target_repo)
+                        throw new Error('transfer 操作必须提供 target_repo [owner/repo]');
+                    if (args.target_repo === repoTarget) {
+                        throw new Error(`transfer 目标仓库 (${args.target_repo}) 与当前仓库相同，迁移无意义。`);
+                    }
+                    // 跨仓库迁移：原 URL 301 但归属改变，不可静默撤回——与 delete 同级 confirm
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            warning: `⚠️ 高危操作拦截：你即将把 Issue #${args.issue_number} 从 ${repoTarget} 迁移到 ${args.target_repo}。`,
+                            impact: `迁移后 Issue 归属 ${args.target_repo}（原 URL 301 重定向），标签/里程碑不随迁，操作不可静默撤回。需要目标仓库的写权限。`,
+                            requiredAction: '如确认迁移，请与用户核实后附加 `confirm: true` 重新调用。',
+                        };
+                    }
+                    const res = await executor.run(['issue', 'transfer', String(args.issue_number), args.target_repo, ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { message: `Issue #${args.issue_number} 已迁移至 ${args.target_repo}`, url: res.rawOutput };
+                }
+                case 'status': {
+                    // 非 TTY 纯文本分段（Assigned/Mentioning/Pushed），gh 原生已是紧凑格式
+                    const res = await executor.run(['issue', 'status', ...repoArgs], { ...runOpts, rawText: true, timeoutMs: 20_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { result: res.rawOutput || '无分配议题' };
+                }
                 default:
                     throw new Error(`未知的 Issue 操作: ${args.action}`);
             }

package/lib/tools/pr.d.ts

@@ -52,6 +52,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            undo: {
+                type: string;
+                description: string;
+            };
             state: {
                 type: string;
                 enum: string[];

package/lib/tools/pr.js

@@ -18,8 +18,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'],
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片（UI 变更对比图、复现截图等）到本地并以图片内容块返回，供 Agent 审查时直接查看。merge/revert 需 confirm: true（revert 在远端创建反向提交与新 PR）。',
                 },
                 pr_number: {
                     type: 'number',
@@ -61,7 +61,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',
@@ -303,6 +307,49 @@ 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 };
+                }
                 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;