dsh-github-flow 0.6.0 → 0.7.1

package/lib/tools/help.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 const KNOWLEDGE_BASE = {
     overview: `### 🧭 DSH GitHub Flow 工具箱全景导航
 
@@ -15,19 +16,21 @@ 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——它们不是业务动作）。
+📄 **长正文走文件，别塞进 body**：正文/发版说明/请求体/prompt 若已经写成本地 md 文件，直接用 \`body_file\` / \`notes_file\` / \`input_file\` / \`prompt_file\` 指向它，不要把全文内联——插件读文件、正文经 stdin 交给 gh，既不占模型上下文，也不会撞上 Windows 的命令行长度上限。
+📊 **规模口径**：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 树 + 按需失败日志），无需跳浏览器；提交详情里的「文件变更统计」与未提交清单里的文件均可弹窗预览该文件的 Unified Diff（整包补丁按文件切分、重命名路径自动归一、超长补丁按文件边界截断）。
 🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
@@ -50,6 +53,8 @@ const KNOWLEDGE_BASE = {
   - 将基准分支最新提交同步进 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 对称闭环。
+- **长正文走本地文件**: \`github_pr(action: 'create', title: '重构方案', body_file: './PR_BODY.md')\`
+  - \`body_file\` 与 \`body\` 二选一，适用于 create/edit/comment/review 四个动作（review 的行级评注走 REST，正文同样可由文件提供）；相对路径按当前工作区解析，文件必须是合法 UTF-8（GBK/ANSI 会明确报错），正文上限 65,536 字符；插件读文件后经 \`--body-file -\` 走 stdin，正文不进模型上下文。
 - **追加评论与编辑**: \`github_pr(action: 'comment', pr_number: 123, body: 'LGTM'); github_pr(action: 'edit', pr_number: 123, body: '更新后的描述')\`
   - 两者同样支持 \`attach_images\` 附件通道。`,
     issue: `### 🎯 github_issue 详细操作指南
@@ -63,6 +68,8 @@ const KNOWLEDGE_BASE = {
   - 触达目录上限时返回 \`remaining\` 结构化清单，直接作为下一批 image_urls 续传即可。
 - **上传本地附件/图片**: \`github_issue(action: 'comment', issue_number: 42, body: '复现证据', attach_images: ['./bug.png'])\`
   - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个本地文件（绝对路径或工作区相对路径，禁止网络 URL）。
+- **长正文走本地文件**: \`github_issue(action: 'create', title: '周报：本周修复清单', body_file: './report.md')\`
+  - \`body_file\` 与 \`body\` 二选一（同时给出会直接报错，不做静默优先级）；相对路径按当前工作区解析，文件必须是合法 UTF-8（GBK/ANSI 会明确报错），正文上限 65,536 字符；插件读文件后经 \`--body-file -\` 走 stdin，正文不进模型上下文。
 - **关联开发分支**: \`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'])\`
@@ -92,7 +99,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')\`
@@ -119,6 +130,9 @@ const KNOWLEDGE_BASE = {
   - 附加 \`Accept: application/vnd.github.raw\`，返回纯文本而非 base64 包装。
 - **全量聚合翻页**:
   \`github_api(endpoint: 'repos/owner/repo/commits', paginate: true)\`
+- **长请求体走本地文件**:
+  \`github_api(endpoint: 'repos/owner/repo/issues', method: 'POST', input_file: './payload.json')\`
+  - 映射 \`--input -\`（插件读文件后经 stdin 交给 gh，省去把 JSON 塞进参数）；与 \`fields\` **不互斥**：两者同时给出时 \`fields\` 作为 URL 查询参数、文件内容作为请求体；请求体不是 GitHub 正文，不受 65,536 字符的正文口径约束。
 - **GraphQL 请求**:
   \`github_api(endpoint: 'graphql', fields: { query: 'query { viewer { login } }' })\``,
     release: `### 🏷️ github_release 版本发布指南
@@ -128,6 +142,8 @@ const KNOWLEDGE_BASE = {
 - **创建 Release（自动生成说明）**:
   \`github_release(action: 'create', tag: 'v0.1.9', generate_notes: true, prerelease: false)\`
   - 若远端尚无该 Tag，gh 会自动从 target 分支（默认主分支）最新提交打 Tag。
+- **用本地 md 作为发版说明**: \`github_release(action: 'create', tag: 'v0.1.9', notes_file: './RELEASE_NOTES.md')\`
+  - \`notes_file\` 与 \`notes\` 二选一（映射 \`--notes-file -\`）；相对路径按当前工作区解析，文件必须是合法 UTF-8、不超过 4MB；**发版说明不套用正文的 65,536 字符口径**（GitHub 对 Release 说明的上限宽得多），长说明写进文件即可，不必先读进上下文再原样回填。
 - **上传构建资产**:
   \`github_release(action: 'upload', tag: 'v0.1.9', assets: ['./dsh-github-flow-0.1.9.tgz'])\`
   - 覆盖同名旧资产必须附加 \`clobber: true, confirm: true\`（旧资产删除后不可恢复）。
@@ -203,8 +219,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 +247,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 云端智能体会话：
@@ -249,6 +265,8 @@ const KNOWLEDGE_BASE = {
 - **检视讨论正文与回复楼层**: \`github_discussion(action: 'view', discussion_number: 123, comments: true)\`
 - **发起新讨论**: \`github_discussion(action: 'create', title: 'RFC: 架构演进方案', category: 'Ideas', body: '详细方案...')\`
   - \`title\`、\`category\` 与 \`body\` 均为必填项。
+- **长正文走本地文件**: \`github_discussion(action: 'create', title: 'RFC: 架构演进方案', category: 'Ideas', body_file: './rfc.md')\`
+  - \`body_file\` 与 \`body\` 二选一（\`title\` / \`category\` 仍必填，映射 \`--body-file -\`）；相对路径按当前工作区解析，文件必须是合法 UTF-8，正文上限 65,536 字符；RFC 动辄数千字，写进文件比塞进参数更省上下文。
 - **编辑讨论**: \`github_discussion(action: 'edit', discussion_number: 123, title: '新标题', body: '修正后的正文')\`
 - **发表讨论回复**: \`github_discussion(action: 'comment', discussion_number: 123, body: '赞同该方案！')\`
 - 💡 **提示**：若报错「discussions disabled」，说明目标仓库未在 GitHub 仓库「Settings -> General -> Features」中启用 Discussions 社区功能。`,
@@ -275,6 +293,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')\` 完全一致；整体审阅说明若已写成本地 md，改用 \`body_file\`（与 \`body\` 二选一，写回走 REST 请求体）。
+- **诊断一次 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 +399,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 +409,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,8 +461,10 @@ 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）
+- 本地文件正文：\`gh issue create -F report.md\` 的等价写法是 \`github_issue(action:'create', body_file:'report.md')\`——「本地 md → Issue/PR/讨论/发版说明/请求体/任务 prompt」这条通道已由插件覆盖，文件由插件读取、正文经 stdin 交给 gh，**不经过模型上下文**；对应参数分别是 \`body_file\`（issue / pr / discussion / task）、\`notes_file\`（release）、\`input_file\`（api）、\`prompt_file\`（agent_task），相对路径按当前工作区解析
 
 #### 三、未覆盖域引导（经 github_api 调用）
 
@@ -472,10 +518,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 +554,7 @@ export function createHelpTool(executor) {
                         'discussion',
                         'project',
                         'codespace',
+                        'task',
                         'mapping',
                         'search_syntax',
                         'troubleshooting',
@@ -526,8 +579,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 +609,5 @@ export function createHelpTool(executor) {
                 result: `未找到主题「${rawTopic}」的指南。可用主题：${Object.keys(KNOWLEDGE_BASE).join(', ')}。`,
             };
         },
-    };
+    });
 }

package/lib/tools/issue.d.ts

@@ -36,6 +36,10 @@ export declare function createIssueTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            body_file: {
+                type: string;
+                description: string;
+            };
             labels: {
                 type: string;
                 items: {

package/lib/tools/issue.js

@@ -1,6 +1,9 @@
+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';
+import { resolveBodySource } from './body-input.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -13,7 +16,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: {
@@ -47,7 +50,11 @@ export function createIssueTool(executor) {
                 },
                 body: {
                     type: 'string',
-                    description: 'Issue 描述正文或追加评论内容（create, comment, edit 时使用）。',
+                    description: 'Issue 描述正文或追加评论内容（create, comment, edit 时使用）。与 body_file 二选一。',
+                },
+                body_file: {
+                    type: 'string',
+                    description: '正文来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 body 二选一；长正文用本参数，无需把全文读进上下文。',
                 },
                 labels: {
                     type: 'array',
@@ -108,8 +115,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);
@@ -122,6 +130,8 @@ export function createIssueTool(executor) {
             }
             const repoArgs = ['-R', repoTarget];
             const runOpts = { cwd, sessionId };
+            // 正文来自本地文件时经 stdin 注入（`--body-file -`）：绕开 Windows 约 32K 的命令行上限
+            const stdinPatch = (body) => (body.stdin === undefined ? {} : { stdin: body.stdin });
             const appendAttachFlags = async (cmd, attachImages) => {
                 const attachPaths = validateAttachPaths(attachImages, cwd);
                 if (attachPaths.length > 0) {
@@ -227,7 +237,8 @@ export function createIssueTool(executor) {
                     };
                 }
                 case 'create': {
-                    const cmd = ['issue', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd, keepEmptyInline: true });
+                    const cmd = ['issue', 'create', ...repoArgs, '--title', args.title || '', ...body.argv];
                     if (args.labels && Array.isArray(args.labels) && args.labels.length > 0) {
                         cmd.push('--label', args.labels.join(','));
                     }
@@ -235,7 +246,7 @@ export function createIssueTool(executor) {
                         cmd.push('--assignee', args.assignees.join(','));
                     }
                     await appendAttachFlags(cmd, args.attach_images);
-                    const res = await executor.run(cmd, runOpts);
+                    const res = await executor.run(cmd, { ...runOpts, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: 'Issue 创建成功', url: res.rawOutput };
@@ -243,11 +254,11 @@ export function createIssueTool(executor) {
                 case 'edit': {
                     if (!args.issue_number)
                         throw new Error('edit 操作必须提供 issue_number');
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
                     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);
+                    editCmd.push(...body.argv);
                     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);
@@ -257,7 +268,7 @@ export function createIssueTool(executor) {
                             editCmd.push('--remove-label', l);
                     }
                     await appendAttachFlags(editCmd, args.attach_images);
-                    const res = await executor.run(editCmd, runOpts);
+                    const res = await executor.run(editCmd, { ...runOpts, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: `Issue #${args.issue_number} 更新成功`, output: res.rawOutput };
@@ -265,6 +276,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);
@@ -275,11 +295,14 @@ export function createIssueTool(executor) {
                     return { message: `已成功为 Issue #${args.issue_number} 创建并检出开发分支`, output: res.rawOutput };
                 }
                 case 'comment': {
-                    if (!args.issue_number || !args.body)
-                        throw new Error('comment 必须提供 issue_number 和 body');
-                    const commentCmd = ['issue', 'comment', String(args.issue_number), ...repoArgs, '--body', args.body];
+                    if (!args.issue_number)
+                        throw new Error('comment 操作必须提供 issue_number');
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
+                    if (body.chars === 0)
+                        throw new Error('comment 必须提供 body 或 body_file（评论正文）');
+                    const commentCmd = ['issue', 'comment', String(args.issue_number), ...repoArgs, ...body.argv];
                     await appendAttachFlags(commentCmd, args.attach_images);
-                    const res = await executor.run(commentCmd, runOpts);
+                    const res = await executor.run(commentCmd, { ...runOpts, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: '评论发布成功', output: res.rawOutput };
@@ -287,14 +310,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 +355,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 +370,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 +386,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

@@ -27,6 +27,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            body_file: {
+                type: string;
+                description: string;
+            };
             base: {
                 type: string;
                 description: string;
@@ -44,6 +48,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 +100,10 @@ export declare function createPrTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            force: {
+                type: string;
+                description: string;
+            };
             undo: {
                 type: string;
                 description: string;