dsh-github-flow 0.6.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 工具箱全景导航
 
@@ -15,19 +16,20 @@ const KNOWLEDGE_BASE = {
 | \`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\`。
-📊 **规模口径**：18 个工具 / 103 个业务 action（不含 \`github_help\` 的 21 个查询主题与 \`github_api\` 的 4 个 HTTP method——它们不是业务动作）。
+📊 **规模口径**：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 卡片可在线查看详情与评论，无需跳浏览器。
+🖥️ **可视化工作台**：最左侧 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 详细操作指南
 
@@ -92,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')\`
@@ -203,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\` 保证幂等执行。`,
@@ -231,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 云端智能体会话：
@@ -275,6 +281,24 @@ 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 精确对照）
@@ -363,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 命令 | 插件调用 | 备注 |
@@ -373,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 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
@@ -417,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）
 
@@ -472,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: {
@@ -502,6 +541,7 @@ export function createHelpTool(executor) {
                         'discussion',
                         'project',
                         'codespace',
+                        'task',
                         'mapping',
                         'search_syntax',
                         'troubleshooting',
@@ -526,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+/);
@@ -557,5 +596,5 @@ export function createHelpTool(executor) {
                 result: `未找到主题「${rawTopic}」的指南。可用主题：${Object.keys(KNOWLEDGE_BASE).join(', ')}。`,
             };
         },
-    };
+    });
 }

package/lib/tools/issue.js

@@ -1,6 +1,8 @@
+import { wrapWithGate } from '../destructive.js';
 import { compareGhVersions } from '../executor.js';
 import { renderIssueMarkdown } from '../renderers/markdown.js';
 import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls, validateAttachPaths } from './image-utils.js';
+import { assertPositionArg } from '../executor/args-guard.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -13,7 +15,7 @@ function normalizeOutput(data) {
 // 共享图片工具链的同名再导出：保持路径与单测稳定
 export { extractImageUrls as extractIssueImageUrls, validateAttachPaths } from './image-utils.js';
 export function createIssueTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_issue',
         description: '管理 GitHub Issues。支持查看 Issue 列表、详情、创建新 Issue、追加评论、关闭 Issue、编辑 Issue 以及关联创建本地开发分支 (develop)。',
         parameters: {
@@ -108,8 +110,9 @@ export function createIssueTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // 位置参数守卫：issue_number 是 `gh issue <cmd> <number>` 的位置参数
+            assertPositionArg(args.issue_number, 'Issue 编号');
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             let repoTarget = args.repo;
             if (!repoTarget) {
                 const meta = await executor.getRepoMetadata(cwd, sessionId);
@@ -265,6 +268,15 @@ export function createIssueTool(executor) {
                 case 'develop': {
                     if (!args.issue_number)
                         throw new Error('develop 操作必须提供 issue_number');
+                    // `--checkout` 会把工作区切到新分支，脏改动会被一起带走——与界面切分支同源风险，
+                    // 必须过同一道闸门（executor.ensureCleanWorkspace，唯一实现）。
+                    const guard = await executor.ensureCleanWorkspace(cwd);
+                    if (!guard.ok) {
+                        const sample = guard.samples.length
+                            ? `\n涉及文件（前 ${guard.samples.length} 条）：\n${guard.samples.map((s) => '  ' + s).join('\n')}`
+                            : '';
+                        throw new Error(`${guard.error}${sample}\n请先提交或 stash 后再创建并检出开发分支。`);
+                    }
                     const devCmd = ['issue', 'develop', String(args.issue_number), ...repoArgs, '--checkout'];
                     if (args.branch_name) {
                         devCmd.push('-n', args.branch_name);
@@ -287,14 +299,6 @@ 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);
@@ -340,14 +344,6 @@ export function createIssueTool(executor) {
                     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)
@@ -363,14 +359,6 @@ export function createIssueTool(executor) {
                         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);
@@ -387,5 +375,5 @@ export function createIssueTool(executor) {
                     throw new Error(`未知的 Issue 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/label.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderLabelMarkdown } from '../renderers/markdown.js';
 /**
  * 校验并归一化 6 位十六进制颜色（去除前导 #）
@@ -21,7 +22,7 @@ function normalizeOutput(data) {
     return { result: data !== undefined && data !== null ? data : '' };
 }
 export function createLabelTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_label',
         description: '管理 GitHub 仓库标签体系 (Labels)：查看标签列表、创建新标签、编辑修改现有标签、克隆跨仓库标签体系 (clone) 以及安全删除标签。删除操作不可逆且会解绑议题，需 confirm: true。',
         parameters: {
@@ -92,8 +93,7 @@ export function createLabelTool(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);
             let repoTarget = args.repo;
             if (!repoTarget) {
                 const meta = await executor.getRepoMetadata(cwd, sessionId);
@@ -188,17 +188,6 @@ export function createLabelTool(executor) {
                     if (!args.name) {
                         throw new Error('删除标签时 `name` 参数为必填项。');
                     }
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            action: 'delete',
-                            name: args.name,
-                            repo: repoTarget,
-                            warning: `⚠️ 高危破坏性操作：即将删除仓库 ${repoTarget} 的标签 "${args.name}"`,
-                            impact: `删除标签不可逆，且会导致目标仓库内所有已打上该标签的 Issue 与 PR 自动解绑该标记。`,
-                            requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_label(action: 'delete', name: '${args.name}', confirm: true)\``,
-                        };
-                    }
                     const deleteCmd = ['label', 'delete', args.name, '--yes', ...repoArgs];
                     const res = await executor.run(deleteCmd, runOpts);
                     if (!res.ok)
@@ -233,5 +222,5 @@ export function createLabelTool(executor) {
                     throw new Error(`不支持的 label 操作: "${args.action}"。可选值: list, create, edit, delete, clone。`);
             }
         },
-    };
+    });
 }

package/lib/tools/pr.d.ts

@@ -44,6 +44,49 @@ export declare function createPrTool(executor: GhExecutor): {
                 enum: string[];
                 description: string;
             };
+            /**
+             * 行级评注（review 动作使用）。
+             *
+             * 为什么必须单独一个参数而不是塞进 body：`gh pr review` 没有行级参数
+             * （`gh pr review --help` 里 line/side/path 零命中），只能走
+             * `POST /pulls/{n}/reviews` 的 `comments[]`。一次 review 一个请求 =
+             * 通知只发一轮，也避开 secondary rate limit 的「创建内容过快」。
+             */
+            comments: {
+                type: string;
+                items: {
+                    type: string;
+                    properties: {
+                        path: {
+                            type: string;
+                            description: string;
+                        };
+                        line: {
+                            type: string;
+                            description: string;
+                        };
+                        side: {
+                            type: string;
+                            enum: string[];
+                            description: string;
+                        };
+                        start_line: {
+                            type: string;
+                            description: string;
+                        };
+                        body: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+                description: string;
+            };
+            commit_id: {
+                type: string;
+                description: string;
+            };
             merge_method: {
                 type: string;
                 enum: string[];
@@ -53,6 +96,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            force: {
+                type: string;
+                description: string;
+            };
             undo: {
                 type: string;
                 description: string;