dsh-github-flow 0.5.0 → 0.7.0

package/lib/tools/codespace.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderCodespaceMarkdown } from '../renderers/markdown.js';
 import { checkScopeRequired } from './project.js';
 function normalizeOutput(data) {
@@ -12,7 +13,7 @@ function normalizeOutput(data) {
 const CODESPACE_LIST_FIELDS = 'name,displayName,repository,owner,state,gitStatus,lastUsedAt,createdAt,machineName';
 const CODESPACE_VIEW_FIELDS = 'name,displayName,repository,owner,state,gitStatus,lastUsedAt,createdAt,machineName,devcontainerPath,recentFolders,idleTimeoutMinutes';
 export function createCodespaceTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_codespace',
         description: '管理 GitHub Codespaces 云端远程开发环境：查阅实例列表与运行状态、检视实例配置详情、停止运行中的环境防计费、安全销毁实例。未授权时提供平台感知自愈命令。',
         parameters: {
@@ -53,8 +54,7 @@ export function createCodespaceTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const runOpts = { cwd, sessionId };
             switch (args.action) {
                 case 'list': {
@@ -123,14 +123,6 @@ export function createCodespaceTool(executor) {
                         throw new Error('delete 操作必须提供 codespace 名称');
                     }
                     const cleanName = args.codespace.trim();
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 销毁确认拦截：你即将永久删除云端开发环境「${cleanName}」。`,
-                            impact: '物理销毁 Codespace 将永久释放云端计算资源，环境中任何未提交并推送到远端 Git 的临时修改都将无法找回。',
-                            requiredAction: '如确认销毁该实例，请核对环境名称并在参数中附加 `confirm: true` 重新调用。',
-                        };
-                    }
                     const deleteCmd = ['codespace', 'delete', '-c', cleanName, '-f'];
                     if (args.org)
                         deleteCmd.push('-o', String(args.org).trim());
@@ -150,5 +142,5 @@ export function createCodespaceTool(executor) {
                     throw new Error(`未知的 Codespace 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/discussion.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderDiscussionMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
@@ -11,7 +12,7 @@ function normalizeOutput(data) {
 const DISCUSSION_LIST_FIELDS = 'number,title,body,category,author,closed,createdAt,updatedAt,url,labels,answered,stateReason';
 const DISCUSSION_VIEW_FIELDS = 'number,title,body,category,author,state,createdAt,updatedAt,url,labels,answered,comments';
 export function createDiscussionTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_discussion',
         description: '管理 GitHub Discussions 讨论区：浏览社区讨论、检视讨论详情与回复楼层、发起新讨论议题、编辑现有讨论以及追加评论回复。基于 gh CLI preview 特性。',
         parameters: {
@@ -74,8 +75,7 @@ export function createDiscussionTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const repoArgs = args.repo ? ['-R', args.repo] : [];
             const runOpts = { cwd, sessionId };
             switch (args.action) {
@@ -191,5 +191,5 @@ export function createDiscussionTool(executor) {
                     throw new Error(`未知的 Discussion 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/gist.d.ts

@@ -71,14 +71,9 @@ export declare function createGistTool(executor: GhExecutor): {
         public?: undefined;
         description?: undefined;
         success?: undefined;
+        gist_id?: undefined;
         message?: undefined;
         detail?: undefined;
-        status?: undefined;
-        action?: undefined;
-        gist_id?: undefined;
-        warning?: undefined;
-        impact?: undefined;
-        requiredAction?: undefined;
     } | {
         items?: undefined;
         count?: undefined;
@@ -92,11 +87,6 @@ export declare function createGistTool(executor: GhExecutor): {
         success?: undefined;
         message?: undefined;
         detail?: undefined;
-        status?: undefined;
-        action?: undefined;
-        warning?: undefined;
-        impact?: undefined;
-        requiredAction?: undefined;
     } | {
         items?: undefined;
         count?: undefined;
@@ -110,11 +100,6 @@ export declare function createGistTool(executor: GhExecutor): {
         description: any;
         message: string;
         detail?: undefined;
-        status?: undefined;
-        action?: undefined;
-        warning?: undefined;
-        impact?: undefined;
-        requiredAction?: undefined;
     } | {
         items?: undefined;
         count?: undefined;
@@ -128,28 +113,5 @@ export declare function createGistTool(executor: GhExecutor): {
         gist_id: string;
         message: string;
         detail: string;
-        status?: undefined;
-        action?: undefined;
-        warning?: undefined;
-        impact?: undefined;
-        requiredAction?: undefined;
-    } | {
-        items?: undefined;
-        count?: undefined;
-        rawText?: undefined;
-        filename?: undefined;
-        content?: undefined;
-        url?: undefined;
-        public?: undefined;
-        description?: undefined;
-        success?: undefined;
-        message?: undefined;
-        detail?: undefined;
-        status: string;
-        action: string;
-        gist_id: string;
-        warning: string;
-        impact: string;
-        requiredAction: string;
     }>;
 };

package/lib/tools/gist.js

@@ -1,6 +1,7 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderGistMarkdown, parseGistListOutput } from '../renderers/markdown.js';
 export function createGistTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_gist',
         description: '管理 GitHub Gist 代码片段与诊断留痕：查看 Gist 列表、检视代码正文 (view)、通过文本内容或本地文件创建新 Gist (create，默认安全 secret 模式)、编辑以及安全删除。删除操作不可逆，需 confirm: true。',
         parameters: {
@@ -58,8 +59,7 @@ export function createGistTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const runOpts = { cwd, sessionId, rawText: true };
             switch (args.action) {
                 case 'list': {
@@ -161,16 +161,6 @@ export function createGistTool(executor) {
                     if (!args.gist_id) {
                         throw new Error('删除 Gist 时 `gist_id` 参数为必填项。');
                     }
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            action: 'delete',
-                            gist_id: String(args.gist_id),
-                            warning: `⚠️ 高危破坏性操作：即将永久删除 Gist 代码片段 "${args.gist_id}"`,
-                            impact: `删除 Gist 为物理删除，无法通过 GitHub API 恢复，所有引用该 Gist URL 的外部链接将失效并返回 404。`,
-                            requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_gist(action: 'delete', gist_id: '${args.gist_id}', confirm: true)\``,
-                        };
-                    }
                     const delCmd = ['gist', 'delete', String(args.gist_id), '--yes'];
                     const res = await executor.run(delCmd, runOpts);
                     if (!res.ok)
@@ -186,5 +176,5 @@ export function createGistTool(executor) {
                     throw new Error(`不支持的 gist 操作: "${args.action}"。可选值: list, view, create, edit, delete。`);
             }
         },
-    };
+    });
 }

package/lib/tools/help.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 const KNOWLEDGE_BASE = {
     overview: `### 🧭 DSH GitHub Flow 工具箱全景导航
 
@@ -12,20 +13,23 @@ const KNOWLEDGE_BASE = {
 | \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
 | \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
 | \`github_secret\` | CI/CD 密钥与变量管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥；kind:'variable' 管理明文变量（set/get/delete） |
-| \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
+| \`github_skill\` | 跨 Agent 开源 Skills 生态发现与维护 | 检索/预览/安装 GitHub 上的 Agent Skills（gh preview 特性）；\`publish\` 规范自检与发布、\`update\` 检查并同步更新已安装技能 |
 | \`github_label\` | 标签体系管理与跨仓库克隆 | 查看标签列表、创建/编辑标签、从源仓库一键 clone 标签体系、删除标签（需 confirm） |
 | \`github_ruleset\` | 分支保护规则与策略诊断 | 检查分支适用的合并策略规则 (check)、查看规则集列表与详情，权威回答“PR 为何无法合并” |
-| \`github_cache\` | Actions 构建缓存盘点与安全清理 | 查看缓存列表与体积占用、按 ID/Key 删除指定缓存、全量清空缓存（需 confirm） |
+| \`github_cache\` | Actions 构建缓存盘点与安全清理 | 查看缓存列表与体积占用、按 ID/Key 删除指定缓存、删除缓存（三态均需 confirm） |
 | \`github_gist\` | 代码片段与调试日志分享治理 | 查看 Gist 列表与代码正文、创建 Secret/Public 代码片段、编辑与物理删除（需 confirm） |
 | \`github_status\` | 跨仓库待办与动态聚合看板 | 账号维度汇总指派给我的 Issue/PR、等待评审、被 @提及 以及订阅仓库近期动态 |
 | \`github_agent_task\` | 云端智能体编码任务会话治理 | 查阅已分派任务列表、检视任务状态与会话日志、向云端 Agent 发起新编码重构任务 |
 | \`github_discussion\` | 团队技术讨论与开源社区 RFC 闭环 | 浏览讨论列表、检视正文与评论楼层、发起新讨论、编辑正文与追加回复 |
 | \`github_project\` | Projects v2 项目看板与任务规划 | 查阅项目列表/详情、浏览看板条目 (Items)、添加 Issue/PR 到看板、创建草稿任务与删除条目 |
 | \`github_codespace\` | 云端远程开发环境管控 (MVP) | 查阅运行中实例、检视机器规格配置、停机防计费 (stop)、安全销毁环境 (delete，需 confirm) |
+| \`github_task\` | **任务级原语**（一次调用完成一件完整的事） | 审一个 PR（元数据 + diff + CI + 仓库规则，可选写回行级评注）、诊断一次 CI 失败（定位 job/step + 日志锚点）、准备一次发版（Conventional Commits 归类 + SemVer + notes 草稿）；默认只读 |
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
 💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+📊 **规模口径**：19 个工具 / 106 个业务 action（不含 \`github_help\` 的 22 个查询主题与 \`github_api\` 的 4 个 HTTP method——它们不是业务动作）。
 💬 **人类指令**：聊天框支持 \`/gh status\`（大盘看板）、\`/gh upgrade\`（一键升级插件）、\`/gh help\`（快捷帮助）。
+🖥️ **可视化工作台**：最左侧 Octocat 图标打开全景驾驶舱（4 标签：本地工作区 / 我的仓库 / Pull Requests / 待办 Issues）；每个会话右侧栏有 5 个 Tab（Git / 未提交 / PR / Issues / Actions）。PR、Issue、Actions 三类卡片点击均可在线查看详情（Actions 为 job / step 树 + 按需失败日志），无需跳浏览器。
 🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
@@ -47,7 +51,9 @@ const KNOWLEDGE_BASE = {
 - **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
   - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。
 - **上传本地附件/图片**: \`github_pr(action: 'create', title: 'UI 重构', body: '对比图如下', attach_images: ['./before.png', './after.png'])\`
-  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。`,
+  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。
+- **追加评论与编辑**: \`github_pr(action: 'comment', pr_number: 123, body: 'LGTM'); github_pr(action: 'edit', pr_number: 123, body: '更新后的描述')\`
+  - 两者同样支持 \`attach_images\` 附件通道。`,
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
@@ -88,7 +94,11 @@ const KNOWLEDGE_BASE = {
 - **启停工作流**: \`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 隔离），返回文件清单。`,
+  - 落盘目录由插件固定管理（\`~/.dsh/data/dsh-github-flow/artifacts/\` 下按仓库与 run 隔离），返回文件清单。
+- **看单次运行的 job / step 结构**: \`github_run(action: 'view', run_id: '12345678')\`
+  - 返回 run 元数据 + jobs 树（每个 job 的 conclusion、起止时间、url，以及 steps 的 number/name/conclusion）；这是「挂在第几步」最快的入口。
+- **人类侧在线查看（不是工具调用）**: 右侧栏 Actions Tab 点击任一卡片 → job / step 树 + 失败步骤高亮 + 按需日志锚点（一次最多 3 个失败 job、服务端批次预算 90 秒）。
+  - Agent 侧的等价快捷方式是 \`github_task(action: 'diagnose_ci', run_id: '12345678')\`：定位失败 job/step → 萃取日志锚点 → 汇总疑似相关文件，一次返回结论包。`,
     repo: `### 📦 github_repo 详细操作指南
 
 - **查看元数据与标签**: \`github_repo(action: 'view')\`
@@ -164,7 +174,13 @@ const KNOWLEDGE_BASE = {
   - \`github_skill(action: 'publish')\` —— 默认 \`--dry-run\` 模式，对本地技能目录进行 agentskills.io 合规性检查（命名规范、目录匹配、必需 frontmatter 字段等），零副作用安全自检。
   - \`github_skill(action: 'publish', fix: true)\` —— 自动清洗并剥离残留的安装元数据（\`metadata.github-*\`），修改本地文件但不发布。
   - \`github_skill(action: 'publish', tag: 'v1.0.0', dry_run: false, confirm: true)\` —— 正式发布，强制要求指定 \`tag\` 并附带 \`confirm: true\`（防无头挂起与误发布），自动创建 GitHub Release。
-- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。
+
+- **检查并同步更新已安装技能**:
+  - \`github_skill(action: 'update')\` —— **默认 dry-run**，只检查哪些技能有新版本，零副作用。
+  - \`github_skill(action: 'update', dry_run: false)\` —— 真正执行同步更新。
+  - \`github_skill(action: 'update', all: true)\` —— 更新全部已安装技能（否则只处理 \`skill_names\` 指定项）。
+  - \`github_skill(action: 'update', skill_names: ['code-review', 'devops'])\` —— 定向更新指定技能。`,
     label: `### 🏷️ github_label 详细操作指南
 
 - **查看标签列表**: \`github_label(action: 'list', limit: 30, search: 'bug')\`
@@ -193,8 +209,8 @@ const KNOWLEDGE_BASE = {
   - 返回仓库 Actions 构建缓存清单、占用体积（自动换算为 KB/MB/GB）、关联 Git Ref 以及最后访问时间。
   - 可附加 \`key: 'npm-cache'\` 过滤特定前缀，或通过 \`ref: 'refs/heads/main'\` 限定分支。
 - **精准删除单条缓存**:
-  - 按数字 ID 删除: \`github_cache(action: 'delete', cache_id: '12345678')\`
-  - 按 Key 键名删除: \`github_cache(action: 'delete', key: 'Linux-npm-18-abcd1234')\`
+  - 按数字 ID 删除: \`github_cache(action: 'delete', cache_id: '12345678', confirm: true)\`
+  - 按 Key 键名删除: \`github_cache(action: 'delete', key: 'Linux-npm-18-abcd1234', confirm: true)\`
 - **全量清空仓库缓存**:
   \`github_cache(action: 'delete', all: true, confirm: true)\`
   - 批量破坏性操作：会导致后续流水线构建重新拉取依赖，必须显式附加 \`confirm: true\`；底层自动注入 \`--succeed-on-no-caches\` 保证幂等执行。`,
@@ -221,7 +237,7 @@ const KNOWLEDGE_BASE = {
 - **排除噪音仓库**: \`github_status(exclude: ['owner/noisy-repo'])\`
   - 过滤高频刷屏但无需关注的仓库活动。
 - **查看工具链运行时健康度**: \`github_status(action: 'health')\`
-  - 审计当前会话 18 大工具矩阵的综合健康分、API 降级率、安全防线拦截频次与针对性自愈建议。`,
+  - 审计当前会话 19 大工具矩阵的综合健康分、API 降级率、安全防线拦截频次与针对性自愈建议。`,
     agent_task: `### 🤖 github_agent_task 智能体任务指南
 
 管理与调度 GitHub Copilot Coding Agent 云端智能体会话：
@@ -265,14 +281,33 @@ const KNOWLEDGE_BASE = {
 - **安全销毁实例**: \`github_codespace(action: 'delete', codespace: 'fuzzy-spoon-69vj', confirm: true)\`
   - 物理销毁不可逆，必须附加 \`confirm: true\`。
 - 🔑 若报缺少权限，在终端执行单行自愈授权命令：\`gh auth refresh -h github.com -s codespace\``,
+    task: `### 🎯 github_task 任务级原语指南
+
+\`github_task\` 把「一件完整的事」封装成一次调用，返回**已裁剪、可直接执行**的结论包：
+\`summary\`（结论）+ \`facts\`（结构化事实）+ \`nextActions\`（下一步）+ \`cost\`（字符数 / gh 调用数 / 耗时）。
+
+- **审一个 PR**: \`github_task(action: 'review_pr', pr_number: 123)\`
+  - 一次拿齐：PR 元数据 + head SHA + 变动文件 diff（按 \`budget_chars\` 裁剪）+ CI 结论 + 仓库 \`AGENTS.md\` 审查规则 + 既有行级评论数。
+  - \`focus: 'security' | 'correctness' | 'perf' | 'style'\` 只影响 summary 的提示语，不改变取数。
+  - **写回**（默认关闭）: \`github_task(action: 'review_pr', pr_number: 123, write: true, confirm: true, body: '…', comments: [{path, line, body}])\`，字段语义与 \`github_pr(action: 'review')\` 完全一致。
+- **诊断一次 CI 失败**: \`github_task(action: 'diagnose_ci', run_id: 456)\` 或 \`github_task(action: 'diagnose_ci', pr_number: 123)\`
+  - 定位失败 job/step → 萃取失败日志锚点（pytest / node / Go / tsc / npm）→ 汇总疑似相关文件。
+  - 日志被截断时 \`truncated.totalUnknown = true\`：**不要据此判断「就这些失败」**。
+- **准备一次发版**: \`github_task(action: 'prepare_release', bump: 'auto')\`
+  - 读最近 tag 以来的提交 → 按 Conventional Commits 归类 → 推导 SemVer（breaking→major / feat→minor / 其余→patch）→ 生成 notes 草稿 + 发版体检（工作区干净 / 同步远端 / CI 绿）。
+  - **本原语不会打 tag、不会 push、不会创建 Release**：发版是人的决定，它只把「该发什么版本、notes 长什么样」准备好，并在 \`nextActions\` 里给出可直接执行的命令。
+
+> 需要细粒度控制时，用对应的原子工具：\`github_pr\` / \`github_run\` / \`github_release\`。原语是快捷方式，不是唯一入口。
+`,
     mapping: `### 🗺️ gh 命令 ↔ 插件工具映射总表
 
 #### 一、已覆盖域映射（语义化 action 精确对照）
 
-**PR（github_pr，13 action）**
+**PR（github_pr，15 action）**
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
-| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作 |
+| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作；edit/comment 支持 attach_images |
+| （PR 图片查看，gh 无对应命令） | \`github_pr(action:'view_images', pr_number:n)\` | 插件独有：正文+评论图片下载并转为可读图像块 |
 | \`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'…)\` | |
@@ -287,6 +322,7 @@ const KNOWLEDGE_BASE = {
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
 | \`gh issue list/view/create/comment/close/reopen/edit\` | \`github_issue(action:…)\` | 基础操作 |
+| （Issue 图片查看，gh 无对应命令） | \`github_issue(action:'view_images', issue_number:n)\` | 插件独有：报障截图转图像块 |
 | \`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)\` | 跨仓库迁移 |
@@ -325,8 +361,11 @@ const KNOWLEDGE_BASE = {
 | \`gh variable list/set/get/delete\` | \`github_secret(action:…, kind:'variable')\` | CI 明文：-b 直传、get 可回显 |
 | （gh secret get 不存在） | — | GitHub 侧加密存储，物理不可读取 |
 
-**Skill（github_skill，5 action）**
-\`gh skill search/preview/install/list/publish\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm。
+**Skill（github_skill，6 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh skill search/preview/install/list/publish\` | \`github_skill(action:…)\` | install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm |
+| \`gh skill update\` | \`github_skill(action:'update')\` | 默认 dry-run 检查；\`all:true\` 或 \`skill_names\` 定向；\`dry_run:false\` 才真正更新 |
 
 **Label（github_label，5 action）**
 | gh 命令 | 插件调用 | 备注 |
@@ -348,7 +387,7 @@ const KNOWLEDGE_BASE = {
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
 | \`gh cache list\` | \`github_cache(action:'list')\` | 缓存盘点与过滤 |
-| \`gh cache delete\` | \`github_cache(action:'delete', cache_id:…)\` | all:true 需 confirm |
+| \`gh cache delete\` | \`github_cache(action:'delete', cache_id:…, confirm:true)\` | 三态均需 confirm |
 
 **Gist（github_gist，5 action）**
 | gh 命令 | 插件调用 | 备注 |
@@ -358,6 +397,14 @@ const KNOWLEDGE_BASE = {
 | \`gh gist edit\` | \`github_gist(action:'edit', gist_id:…)\` | 描述与文件修改 |
 | \`gh gist delete\` | \`github_gist(action:'delete', gist_id:…, confirm:true)\` | 物理删除，需 confirm |
 
+**Task（github_task，3 action）**
+
+| gh 命令 | 插件调用 | 说明 |
+| :--- | :--- | :--- |
+| \`gh pr view\` + \`gh pr diff\` + \`gh pr checks\` | \`github_task(action:'review_pr')\` | 一次拿齐审阅上下文（可选写回行级评注） |
+| \`gh run view --json jobs\` + \`--log-failed\` | \`github_task(action:'diagnose_ci')\` | 定位失败 job/step 并萃取日志锚点 |
+| \`git describe\` + \`git log\` | \`github_task(action:'prepare_release')\` | 推导版本 + 生成 notes 草稿（不发版） |
+
 **Status（github_status，2 action）**
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
@@ -402,6 +449,7 @@ const KNOWLEDGE_BASE = {
 
 - \`gh workflow …\` / \`gh search …\` / \`gh variable …\` 分别归 **github_run / github_repo / github_secret**（不是独立工具）
 - \`gh api\` 的等价物是 \`github_api\`（全端点逃生门，支持 raw/paginate/jq）
+- 人类侧在线查看（PR / Issue / Actions Run 详情弹窗）由插件 HTTP 路由提供（\`/api/github/pr-detail\`、\`/api/github/issue-detail\`、\`/api/github/run-detail\`、\`/api/github/run-logs\`），**不是工具 action**；Agent 侧对应能力分别是 \`github_pr(action:'view')\`、\`github_issue(action:'view')\`、\`github_run(action:'view')\`
 - 图片查看：\`github_issue\`/\`github_pr\` 的 \`view_images\`、\`github_repo\` 的 \`readme\` + image_urls（插件独有能力，gh 无对应命令）
 - 附件上传：\`github_issue\`/\`github_pr\` 的 \`attach_images\` 映射 gh ≥2.99 原生可重复 \`--attach\` flag（支持 create/edit/comment）
 
@@ -457,10 +505,16 @@ const KNOWLEDGE_BASE = {
     - *解法*：需管理员前往 GitHub 网页端 \`Settings -> General -> Features\` 勾选开启 \`Discussions\`。
  8. **操作被拦截提示 \`Awaiting confirmation\`**:
     - *原因*：对于高危破坏性操作（如合并 PR、删除分支、物理删除 Issue、清空构建缓存、删除密钥、销毁 Codespace），插件设置了强制安全确认防线，未确认时绝对不触发底层 CLI。
-    - *解法*：审阅影响评估报告后，在参数中显式传入 \`confirm: true\` 即可放行。`
+    - *解法*：审阅影响评估报告后，在参数中显式传入 \`confirm: true\` 即可放行。
+ 9. **\`log_failed\` 拉取很慢 / 报 \`unexpected EOF\` / 连接被重置**:
+    - *原因*：GitHub 日志接口是「先打包再下载」，实测单次 4–40 秒，走代理时可能被中途掐断；矩阵构建下日志体量随 job 数线性增长。
+    - *解法*：① 先 \`github_run(action:'view')\` 确认到底哪个 job 挂了，只对失败 job 重试；② 换 \`github_task(action:'diagnose_ci')\` 走一次性的结论包（内部同样是锚点萃取，但会顺带汇总相关文件）；③ 仍失败时改用 \`github_api\` 直接拉 job 日志端点，或让用户到 Actions 页面查看完整日志。
+ 10. **人类侧「提取失败日志」为何只给一小段 / 为什么最多 3 个 job**:
+    - *原因*：弹窗内展示的是**锚点萃取后的片段**（失败块 + 上下文，无锚点时回退尾部 200 行），不是完整日志；一次点击最多串行拉 3 个失败 job，服务端总预算 90 秒——这是为了不让一次点击把面板卡住几分钟。
+    - *解法*：需要完整日志或更多 job 时，让用户点弹窗右上角「GitHub ↗」，或由 Agent 用 \`github_run(action:'log_failed')\` / \`github_task(action:'diagnose_ci')\` 分批处理。`
 };
 export function createHelpTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_help',
         description: 'GitHub 工具箱使用指南与官方命令手册。当你不确定该用哪个工具、需要特定操作的高级语法与示例、或排查 GitHub 报错时调用。',
         parameters: {
@@ -487,6 +541,7 @@ export function createHelpTool(executor) {
                         'discussion',
                         'project',
                         'codespace',
+                        'task',
                         'mapping',
                         'search_syntax',
                         'troubleshooting',
@@ -511,8 +566,7 @@ export function createHelpTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             // 1. 若显式指定了 gh_command，直接透传查询官方离线手册
             if (args.gh_command && typeof args.gh_command === 'string') {
                 let parts = args.gh_command.trim().split(/\s+/);
@@ -542,5 +596,5 @@ export function createHelpTool(executor) {
                 result: `未找到主题「${rawTopic}」的指南。可用主题：${Object.keys(KNOWLEDGE_BASE).join(', ')}。`,
             };
         },
-    };
+    });
 }

package/lib/tools/image-utils.d.ts

@@ -37,6 +37,33 @@ export declare function sniffImageMime(buf: Buffer): string | null;
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export declare const IMG_MAX_BYTES: number;
 export declare const IMG_DIR_MAX_BYTES: number;
+export declare const IMG_DIR_LOW_WATERMARK: number;
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export declare function imageStoreDir(): string;
+/** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
+export declare function imageDirSize(dir: string): number;
+export interface LruEvictionResult {
+    freedBytes: number;
+    evictedCount: number;
+    evictedFiles: string[];
+}
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export declare function evictLruImages(dir: string, neededBytes: number, protectFiles?: Set<string>, maxDirBytes?: number, targetBytes?: number): LruEvictionResult;
 export interface DownloadedImage {
     file: string;
     mimeType: string;

package/lib/tools/image-utils.js

@@ -132,12 +132,24 @@ export function sniffImageMime(buf) {
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export const IMG_MAX_BYTES = 5 * 1024 * 1024; // 单图 5MB
 export const IMG_DIR_MAX_BYTES = 15 * 1024 * 1024; // 图片缓存目录总量 15MB
-/** 图片落盘目录（按内容寻址命名，重复下载天然去重） */
-function imageStoreDir() {
+export const IMG_DIR_LOW_WATERMARK = 10 * 1024 * 1024; // LRU 淘汰低水位目标 10MB
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export function imageStoreDir() {
+    const override = (process.env.DSH_IMAGE_DIR || '').trim();
+    if (override)
+        return path.resolve(override);
     return path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'images');
 }
 /** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
-function imageDirSize(dir) {
+export function imageDirSize(dir) {
     let total = 0;
     try {
         for (const f of fs.readdirSync(dir)) {
@@ -150,6 +162,57 @@ function imageDirSize(dir) {
     catch { }
     return total;
 }
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export function evictLruImages(dir, neededBytes, protectFiles = new Set(), maxDirBytes = IMG_DIR_MAX_BYTES, targetBytes = IMG_DIR_LOW_WATERMARK) {
+    const result = { freedBytes: 0, evictedCount: 0, evictedFiles: [] };
+    if (!fs.existsSync(dir))
+        return result;
+    let currentSize = imageDirSize(dir);
+    if (currentSize + neededBytes <= maxDirBytes) {
+        return result;
+    }
+    const candidates = [];
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const name of entries) {
+            const fullPath = path.join(dir, name);
+            if (protectFiles.has(fullPath))
+                continue;
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.isFile()) {
+                    candidates.push({ path: fullPath, size: stat.size, mtime: stat.mtimeMs });
+                }
+            }
+            catch { }
+        }
+    }
+    catch {
+        return result;
+    }
+    candidates.sort((a, b) => a.mtime - b.mtime);
+    for (const item of candidates) {
+        if (currentSize + neededBytes <= maxDirBytes && currentSize <= targetBytes) {
+            break;
+        }
+        try {
+            fs.unlinkSync(item.path);
+            currentSize -= item.size;
+            result.freedBytes += item.size;
+            result.evictedCount++;
+            result.evictedFiles.push(item.path);
+        }
+        catch { }
+    }
+    return result;
+}
 /**
  * 交集过滤：把调用方请求的 URL 硬约束在正文实际提取的合法清单内。
  * 为什么必须交集而非直接信任传入：image_urls 来自模型生成参数，存在幻觉或
@@ -190,6 +253,7 @@ export async function downloadImages(urls, run) {
     const images = [];
     const failures = [];
     const remaining = [];
+    const currentBatchFiles = new Set();
     let budgetExhausted = false;
     // 无张数截断：字节护栏按真实资源消耗逐张判定。触顶后仍继续遍历——
     // 剩余 URL 全部收进 remaining 供 Agent 分批续传，而非静默丢弃。
@@ -213,6 +277,11 @@ export async function downloadImages(urls, run) {
             failures.push(`${url.slice(-24)}: 内容不是图片（魔数校验失败）`);
             continue;
         }
+        // 空间护栏检查：若超出目录上限，优先触发 LRU 淘汰历史文件以腾出预算
+        if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
+            const { freedBytes } = evictLruImages(dir, buf.length, currentBatchFiles);
+            dirSize = Math.max(0, dirSize - freedBytes);
+        }
         if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
             budgetExhausted = true;
             remaining.push(url);
@@ -222,6 +291,7 @@ export async function downloadImages(urls, run) {
         const ext = mime.includes('svg') ? 'svg' : mime.split('/')[1].replace('jpeg', 'jpg');
         const file = path.join(dir, `${crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16)}.${ext}`);
         fs.writeFileSync(file, buf);
+        currentBatchFiles.add(file);
         // 累计已写入量：下张图的总量护栏判定必须基于最新值（否则多图可突破上限）
         dirSize += buf.length;
         images.push({ file, mimeType: mime, url, bytes: buf.length });