dsh-github-flow 0.6.0 → 0.7.1

package/lib/tools/pr.js

@@ -1,6 +1,10 @@
+import { wrapWithGate } from '../destructive.js';
 import { compareGhVersions } from '../executor.js';
 import { renderPrMarkdown } from '../renderers/markdown.js';
+import { assertPositionArg } from '../executor/args-guard.js';
 import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls, validateAttachPaths } from './image-utils.js';
+import { readReviewRules, summarizeSeverity } from '../review-rules.js';
+import { resolveBodySource } from './body-input.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -13,7 +17,7 @@ function normalizeOutput(data) {
 // 共享图片工具链的同名再导出：保持路径与单测稳定
 export { extractImageUrls as extractPrImageUrls, validateAttachPaths } from './image-utils.js';
 export function createPrTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_pr',
         description: '管理与审查 GitHub Pull Request (PR)。支持查看列表、详情、差异比对、CI 检查状态、代码审查、合并操作、本地代码检出 (checkout) 与冲突状态检测 (status)。默认针对当前工作区关联的仓库。',
         parameters: {
@@ -22,7 +26,7 @@ export function createPrTool(executor) {
                 action: {
                     type: 'string',
                     enum: ['list', 'view', 'create', 'diff', 'checks', 'review', 'merge', 'checkout', 'status', 'view_images', 'ready', 'revert', 'update_branch', 'comment', 'edit'],
-                    description: 'PR 操作类型。view_images 下载正文与评论中的图片到本地；create/edit/comment 支持 attach_images 附件上传；merge/revert 需 confirm: true。',
+                    description: 'PR 操作类型。view_images 下载正文与评论中的图片到本地；create/edit/comment 支持 attach_images 附件上传；merge/revert 以及 checkout 的 force 需 confirm: true。',
                 },
                 pr_number: {
                     type: 'number',
@@ -38,7 +42,11 @@ export function createPrTool(executor) {
                 },
                 body: {
                     type: 'string',
-                    description: '创建 PR 或提交 Review 时的内容描述。',
+                    description: '创建 PR 或提交 Review 时的内容描述（create, comment, edit, review 时使用）。与 body_file 二选一。',
+                },
+                body_file: {
+                    type: 'string',
+                    description: '正文来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 body 二选一；长正文用本参数，无需把全文读进上下文。',
                 },
                 base: {
                     type: 'string',
@@ -57,6 +65,33 @@ export function createPrTool(executor) {
                     enum: ['APPROVE', 'REQUEST_CHANGES', 'COMMENT'],
                     description: '代码审查意见判定（review 操作时使用）。',
                 },
+                /**
+                 * 行级评注（review 动作使用）。
+                 *
+                 * 为什么必须单独一个参数而不是塞进 body：`gh pr review` 没有行级参数
+                 * （`gh pr review --help` 里 line/side/path 零命中），只能走
+                 * `POST /pulls/{n}/reviews` 的 `comments[]`。一次 review 一个请求 =
+                 * 通知只发一轮，也避开 secondary rate limit 的「创建内容过快」。
+                 */
+                comments: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: '文件相对路径，必须出现在该 PR 的变动文件清单里。' },
+                            line: { type: 'number', description: '文件内的行号（新侧）。指向未变更行会被 GitHub 拒绝并自动降级为 body 段落。' },
+                            side: { type: 'string', enum: ['LEFT', 'RIGHT'], description: '评论所在侧，默认 RIGHT（新代码）。' },
+                            start_line: { type: 'number', description: '多行评论的起始行（可选，需与 line 同侧）。' },
+                            body: { type: 'string', description: '评注正文。缺省会被补上 [P2] 严重度前缀。' },
+                        },
+                        required: ['path', 'body'],
+                    },
+                    description: '行级评注列表（review 动作使用，上限 50 条）。传入即走 REST reviews 通道；不传则保持原 gh pr review 行为不变。',
+                },
+                commit_id: {
+                    type: 'string',
+                    description: '可选：把 review 钉在指定 commit SHA 上（默认取 PR 当前 head）。分支会移动，需要精确锚定时传 headRefOid。',
+                },
                 merge_method: {
                     type: 'string',
                     enum: ['merge', 'squash', 'rebase'],
@@ -64,7 +99,11 @@ export function createPrTool(executor) {
                 },
                 delete_branch: {
                     type: 'boolean',
-                    description: '合并/revert 后是否删除源分支（merge、revert 操作时使用，默认 false）。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                    description: '合并后是否删除源分支（仅 merge 动作生效，默认 false）。gh pr revert 没有该 flag，传了也不会生效。删除分支不可撤销，只在确认该分支已无用后再开启。',
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'checkout 动作可选：是否强制重置已存在的本地同名分支（映射 gh pr checkout -f）。会丢弃本地未推送提交，必须同时传 confirm: true。默认 false——本地分支与 PR 头已分叉时检出会失败，而不是静默重置。',
                 },
                 undo: {
                     type: 'boolean',
@@ -85,11 +124,11 @@ export function createPrTool(executor) {
                 },
                 stat_only: {
                     type: 'boolean',
-                    description: '是否仅输出文件变动概览（diff 动作使用，映射为 gh pr diff --stat，防止大 PR 爆 Token）。',
+                    description: '是否仅输出文件变动概览（diff 动作使用，改走 gh pr view --json files，防止大 PR 爆 Token）。',
                 },
                 confirm: {
                     type: 'boolean',
-                    description: '高危破坏性操作确认标志（merge 动作或 delete_branch 时必需）。若为 false 则仅输出合并预演警告。',
+                    description: '高危破坏性操作确认标志（merge 动作、delete_branch、或 checkout 且 force: true 时必需）。若为 false 则仅输出影响评估并拦截。',
                 },
                 dry_run: {
                     type: 'boolean',
@@ -115,8 +154,11 @@ export function createPrTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // 位置参数守卫：pr_number 会作为 `gh pr <cmd> <number>` 的位置参数进入 argv，
+            // `--force` 这类值会被 gh 当成选项而不是编号（复核报告 C-01b）。
+            // 放在入口一次校验即可覆盖全部 action，避免 11 处各自写一份。
+            assertPositionArg(args.pr_number, 'PR 编号');
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             let repoTarget = args.repo;
             if (!repoTarget) {
                 const meta = await executor.getRepoMetadata(cwd, sessionId);
@@ -129,6 +171,8 @@ export function createPrTool(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) {
@@ -160,7 +204,10 @@ export function createPrTool(executor) {
                 }
                 case 'view': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const res = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url,comments'], runOpts);
+                    const res = await executor.run(
+                    // headRefOid/baseRefOid：分支会移动，Agent 侧也要能「钉在某个 commit 上」审
+                    // changedFiles + files：清单在 100 条处静默截断，必须成对返回才能判断完整性
+                    ['pr', 'view', ...target, ...repoArgs, '--json', 'number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup,url,comments,headRefName,baseRefName,headRefOid,baseRefOid,changedFiles,files'], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     const out = normalizeOutput(res.data || res.rawOutput);
@@ -174,6 +221,19 @@ export function createPrTool(executor) {
                         }
                     }
                     out.images = Array.from(new Set(bodies.flatMap((b) => extractImageUrls(b))));
+                    /*
+                     * 仓库审查规则注入（AGENTS.md）。
+                     *
+                     * 触发条件明文：仅在 view/review 动作、且工作区确实存在 AGENTS.md 时注入。
+                     * 读不到就**不加这个键**（不是给个空对象）——这样「没有规则」与「规则为空」
+                     * 在输出里可区分，Agent 不会误以为仓库定义了空规则。
+                     */
+                    const changedPaths = Array.isArray(out.files)
+                        ? out.files.map((f) => (f && typeof f.path === 'string' ? f.path : '')).filter(Boolean)
+                        : [];
+                    const rules = readReviewRules(cwd, changedPaths);
+                    if (rules)
+                        out.reviewRules = rules;
                     return out;
                 }
                 case 'view_images': {
@@ -242,11 +302,36 @@ export function createPrTool(executor) {
                 }
                 case 'diff': {
                     const target = args.pr_number ? [String(args.pr_number)] : [];
-                    const diffCmd = ['pr', 'diff', ...target, ...repoArgs];
+                    // gh pr diff 不提供 --stat（实测 gh 2.96.0 直接 unknown flag / exit 1）。
+                    // 文件变更概览的合法来源是 pr view --json files（字段含 path/additions/deletions）。
+                    // 返回值保持 { result: string } 形状——renderPrMarkdown 对 result 字符串直出
+                    // （src/renderers/pr.ts:15），因此这条路渲染层零改动。
                     if (args.stat_only === true) {
-                        diffCmd.push('--stat');
+                        const statRes = await executor.run(['pr', 'view', ...target, ...repoArgs, '--json', 'files,additions,deletions'], runOpts);
+                        if (!statRes.ok)
+                            throw new Error(statRes.error);
+                        const detail = statRes.data || {};
+                        // executor.run 在输出被 24KB 阈值截断时会跳过 JSON.parse（executor.ts:341），
+                        // 此时 data 为空、rawOutput 是被切断的半截 JSON。绝不能把「没解析出来」说成「0 个文件」。
+                        if (!Array.isArray(detail.files)) {
+                            return {
+                                result: '未能解析文件变更清单：gh 输出可能被 24KB 截断阈值切断。请改用 github_pr 的完整 diff 动作，或缩小范围后重试。',
+                            };
+                        }
+                        const rows = detail.files;
+                        // 只说是"本次取到的文件"：gh 的 --json files 在超过 100 个文件时静默截断
+                        // （cli/cli#12522），不能对外声称是完整清单。
+                        const cell = (v) => String(v ?? '').replace(/\|/g, '\\|');
+                        const lines = [
+                            `本次取到 ${rows.length} 个变更文件（+${detail.additions ?? 0} / -${detail.deletions ?? 0}）`,
+                            '',
+                            '| 文件 | 增 | 删 |',
+                            '| :--- | ---: | ---: |',
+                            ...rows.map((f) => `| ${cell(f.path)} | ${f.additions ?? 0} | ${f.deletions ?? 0} |`),
+                        ];
+                        return { result: lines.join('\n') };
                     }
-                    const res = await executor.run(diffCmd, runOpts);
+                    const res = await executor.run(['pr', 'diff', ...target, ...repoArgs], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return { result: res.rawOutput || '无差异内容' };
@@ -254,10 +339,37 @@ export function createPrTool(executor) {
                 case 'checkout': {
                     if (!args.pr_number)
                         throw new Error('checkout 操作必须提供 pr_number');
-                    const checkoutCmd = ['pr', 'checkout', String(args.pr_number), ...repoArgs, '-f'];
+                    // 防线：检出 PR 会切本地分支，与界面切分支同源风险，必须过同一道闸门。
+                    // 这里用硬阻断而不是 confirm 二次确认——没有哪个参数能让「脏工作区检出」变安全，
+                    // 给个 confirm 只会变成一个绕不过去的死循环。
+                    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 后再检出 PR。`);
+                    }
+                    const checkoutCmd = ['pr', 'checkout', String(args.pr_number), ...repoArgs];
+                    // 默认不带 -f。-f 的语义是 Reset the existing local branch to the latest state
+                    // of the pull request（等价 reset --hard，丢弃本地未推送提交）。
+                    // 不带 -f 时，若本地已有同名分支，gh 的行为是 `git checkout <branch>` 再
+                    // `git merge --ff-only <remote>`——只有「已分叉」才失败，不会静默重置。
+                    // 跨 fork 且本地无 remote 时走 `git fetch <ref>:<branch>`（不带 --force），
+                    // 分叉同样会失败。因此默认路径是安全的，真要重置必须 force + confirm 双门。
+                    if (args.force === true) {
+                        checkoutCmd.push('-f');
+                    }
                     const res = await executor.run(checkoutCmd, runOpts);
-                    if (!res.ok)
-                        throw new Error(res.error);
+                    if (!res.ok) {
+                        // gh 在这里抛的是裸 git 错误，对用户和模型都没有"下一步"线索。
+                        // 「PR 被 rebase / force-push 后重新检出」是常见路径，必须给出可操作选项。
+                        const raw = String(res.error || '');
+                        if (/fast-forward|non-fast-forward|rejected/i.test(raw)) {
+                            throw new Error(`本地分支与 PR #${args.pr_number} 的头已分叉，无法快进检出。\n${raw}\n` +
+                                '如确认用 PR 头覆盖本地分支（会丢弃本地未推送提交），请附加 `force: true, confirm: true` 重新调用。');
+                        }
+                        throw new Error(raw);
+                    }
                     return { message: `已成功将 PR #${args.pr_number} 检出至本地分支`, output: res.rawOutput || 'Checked out' };
                 }
                 case 'status': {
@@ -268,7 +380,10 @@ export function createPrTool(executor) {
                     return normalizeOutput(res.data || res.rawOutput);
                 }
                 case 'create': {
-                    const createCmd = ['pr', 'create', ...repoArgs, '--title', args.title || '', '--body', args.body || ''];
+                    // keepEmptyInline：无正文时仍要下发 `--body ''`，否则 gh 会打开编辑器等交互输入，
+                    // 在非 TTY 环境下直接挂起。正文来源与位置保持在 `--title` 之后，老调用 argv 逐字节不变。
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd, keepEmptyInline: true });
+                    const createCmd = ['pr', 'create', ...repoArgs, '--title', args.title || '', ...body.argv];
                     if (args.base)
                         createCmd.push('--base', args.base);
                     // 跨 fork 提 PR 必须显式给出 --head（形如 forkOwner:branch）。
@@ -282,7 +397,7 @@ export function createPrTool(executor) {
                     if (dryRun)
                         createCmd.push('--dry-run');
                     await appendAttachFlags(createCmd, args.attach_images);
-                    const res = await executor.run(createCmd, runOpts);
+                    const res = await executor.run(createCmd, { ...runOpts, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return dryRun
@@ -292,6 +407,61 @@ export function createPrTool(executor) {
                 case 'review': {
                     if (!args.pr_number)
                         throw new Error('review 操作必须提供 pr_number');
+                    /*
+                     * 正文在分支判定之前解析：带 comments 时走的是 REST reviews 通道，那条路没有任何
+                     * `--body-file` 可用，正文只能由插件读出来塞进 JSON。若把解析放在 gh 分支里，
+                     * 「带 comments + body_file」就会静默丢正文——所以两条通道共用这一份结果。
+                     */
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
+                    /*
+                     * 行级评注分支：只有显式传了非空 comments 才走 REST reviews 通道。
+                     * 不传 → 下面的原 gh pr review 路径一字不动（默认行为零变化，这是本改动的
+                     * 首要约束：老调用方的 argv 必须逐字节一致）。
+                     */
+                    const lineComments = Array.isArray(args.comments) ? args.comments : [];
+                    if (lineComments.length > 0) {
+                        const res = await executor.createPrReview(cwd, args.repo, args.pr_number, {
+                            event: args.review_decision,
+                            // createPrReview 侧按 trim 归一，空串与 undefined 等价，直接给权威正文即可
+                            body: body.text,
+                            comments: lineComments,
+                            commit_id: args.commit_id,
+                        });
+                        if (!res.ok)
+                            throw new Error(res.error || 'Review 提交失败');
+                        /*
+                         * 严重度分布汇总（plan §2.3 item 14）。
+                         *
+                         * 为什么在工具层算：`normalizeSeverity` 幂等，这里对**入参**统计与对
+                         * 已提交正文统计等价；而在工具层算不必让 executor 回传审计字段。
+                         * 目的是让调用方一眼看到「这轮意见里有没有 P0」，而不是自己数。
+                         */
+                        const severity = summarizeSeverity([body.text, ...lineComments.map((c) => (c && typeof c.body === 'string' ? c.body : ''))].filter((b) => typeof b === 'string' && b.trim()));
+                        const lines = [
+                            res.degraded
+                                ? `⚠️ Review 已提交（行级评注降级为正文段落）`
+                                : `✅ Review 已提交，含 ${lineComments.length} 条行级评注`,
+                        ];
+                        if (res.data?.htmlUrl)
+                            lines.push(`- 地址: ${res.data.htmlUrl}`);
+                        if (res.data?.state)
+                            lines.push(`- 判定: ${res.data.state}`);
+                        lines.push(`- 严重度: P0×${severity.P0} / P1×${severity.P1} / P2×${severity.P2}`);
+                        if (Array.isArray(res.data?.comments) && res.data.comments.length > 0) {
+                            lines.push('- 已挂载的行级评注:');
+                            for (const c of res.data.comments) {
+                                lines.push(`  - \`${c.path}${c.line ? ':' + c.line : ''}\`${c.htmlUrl ? ' → ' + c.htmlUrl : ''}`);
+                            }
+                        }
+                        if (res.degraded && res.degradedReason)
+                            lines.push(`\n> ⚠️ ${res.degradedReason}`);
+                        return {
+                            result: lines.join('\n'),
+                            severity,
+                            degraded: res.degraded === true,
+                            degradedReason: res.degradedReason,
+                        };
+                    }
                     const reviewCmd = ['pr', 'review', String(args.pr_number), ...repoArgs];
                     if (args.review_decision === 'APPROVE')
                         reviewCmd.push('--approve');
@@ -299,9 +469,9 @@ export function createPrTool(executor) {
                         reviewCmd.push('--request-changes');
                     else
                         reviewCmd.push('--comment');
-                    if (args.body)
-                        reviewCmd.push('--body', args.body);
-                    const res = await executor.run(reviewCmd, runOpts);
+                    // 位置与旧代码一致：`--body` 紧跟判定 flag，老调用 argv 逐字节不变
+                    reviewCmd.push(...body.argv);
+                    const res = await executor.run(reviewCmd, { ...runOpts, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: 'Review 提交成功', detail: res.rawOutput };
@@ -309,14 +479,6 @@ export function createPrTool(executor) {
                 case 'merge': {
                     if (!args.pr_number)
                         throw new Error('merge 操作必须提供 pr_number');
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 高危操作拦截：你即将合并 PR #${args.pr_number}（合并策略: ${args.merge_method || 'squash'}${args.delete_branch ? '，且删除源分支' : ''}）。`,
-                            impact: '合并操作将直接向基准分支写入代码并更新远端 PR 状态。',
-                            requiredAction: '如确认执行合并，请向用户明确确认并附加 `confirm: true` 重新调用。',
-                        };
-                    }
                     const method = args.merge_method === 'merge' ? '--merge' : (args.merge_method === 'rebase' ? '--rebase' : '--squash');
                     const mergeCmd = ['pr', 'merge', String(args.pr_number), ...repoArgs, method];
                     // 删分支默认关闭：合并他人仓库的 PR 时删掉源分支是不可撤销的破坏性动作，
@@ -345,17 +507,9 @@ export function createPrTool(executor) {
                     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');
+                    // 注意：gh pr revert 没有 --delete-branch（实测 2.96.0 unknown flag），
+                    // 不在这里推该 flag；删分支只在 merge 通道支持。
                     const res = await executor.run(revertCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
@@ -372,11 +526,15 @@ export function createPrTool(executor) {
                     return { message: `PR #${args.pr_number} 分支已从基准分支同步更新`, output: res.rawOutput };
                 }
                 case 'comment': {
-                    if (!args.pr_number || !args.body)
-                        throw new Error('comment 必须提供 pr_number 和 body');
-                    const commentCmd = ['pr', 'comment', String(args.pr_number), ...repoArgs, '--body', args.body];
+                    if (!args.pr_number)
+                        throw new Error('comment 操作必须提供 pr_number');
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
+                    // 判空看解析后的权威正文字符数：文件来源时 `args.body` 恒为空，不能拿它做必填判定
+                    if (body.chars === 0)
+                        throw new Error('comment 必须提供 body 或 body_file（评论正文）');
+                    const commentCmd = ['pr', 'comment', String(args.pr_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: 'PR 评论发布成功', output: res.rawOutput };
@@ -384,13 +542,13 @@ export function createPrTool(executor) {
                 case 'edit': {
                     if (!args.pr_number)
                         throw new Error('edit 操作必须提供 pr_number');
+                    const body = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
                     const editCmd = ['pr', 'edit', String(args.pr_number), ...repoArgs];
                     if (args.title)
                         editCmd.push('--title', args.title);
-                    if (args.body)
-                        editCmd.push('--body', args.body);
+                    editCmd.push(...body.argv);
                     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: `PR #${args.pr_number} 更新成功`, output: res.rawOutput };
@@ -399,5 +557,5 @@ export function createPrTool(executor) {
                     throw new Error(`未知的 PR 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/project.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderProjectMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
@@ -24,7 +25,7 @@ export function checkScopeRequired(errorMsg, scope, command, tool) {
     return null;
 }
 export function createProjectTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_project',
         description: '管理 GitHub Projects v2 项目看板与任务规划：查看项目列表与卡片条目、关联 Issue/PR 到看板、创建草稿任务、删除看板条目。未授权时提供平台感知自愈命令。',
         parameters: {
@@ -85,8 +86,7 @@ export function createProjectTool(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 owner = typeof args.owner === 'string' && args.owner.trim() ? args.owner.trim() : '@me';
             const runOpts = { cwd, sessionId };
             switch (args.action) {
@@ -206,15 +206,6 @@ export function createProjectTool(executor) {
                         throw new Error('item-delete 操作必须提供 item_id（条目唯一 ID）');
                     }
                     const cleanItemId = args.item_id.trim();
-                    // 确认防线拦截
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 删除确认拦截：你即将从看板中删除条目（ID: ${cleanItemId}）。`,
-                            impact: '该操作将从项目看板中物理移除该条目（若是关联的 Issue/PR，实体不会被删除，仅解除看板关联）。',
-                            requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
-                        };
-                    }
                     const deleteCmd = [
                         'project', 'item-delete',
                         '--owner', owner,
@@ -237,5 +228,5 @@ export function createProjectTool(executor) {
                     throw new Error(`未知的 Project 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/release.d.ts

@@ -26,6 +26,10 @@ export declare function createReleaseTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            notes_file: {
+                type: string;
+                description: string;
+            };
             generate_notes: {
                 type: string;
                 description: string;

package/lib/tools/release.js

@@ -1,4 +1,7 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderReleaseMarkdown } from '../renderers/markdown.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;
@@ -9,7 +12,7 @@ function normalizeOutput(data) {
     return { result: data !== undefined && data !== null ? data : '' };
 }
 export function createReleaseTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_release',
         description: '管理 GitHub Releases 版本发布与构建资产：查看发版历史、根据提交自动生成发版说明、创建 Release、上传/下载发布资产（如 npm .tgz 产物）。高危操作（delete、clobber 覆盖上传）需 confirm: true。',
         parameters: {
@@ -34,7 +37,11 @@ export function createReleaseTool(executor) {
                 },
                 notes: {
                     type: 'string',
-                    description: 'Release 说明正文（create 动作使用）。留空且 generate_notes 为 true 时将自动由 GitHub 根据提交记录生成。',
+                    description: 'Release 说明正文（create 动作使用）。留空且 generate_notes 为 true 时将自动由 GitHub 根据提交记录生成。与 notes_file 二选一。',
+                },
+                notes_file: {
+                    type: 'string',
+                    description: '发版说明来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 notes 二选一。',
                 },
                 generate_notes: {
                     type: 'boolean',
@@ -91,8 +98,9 @@ export function createReleaseTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            // 位置参数守卫：tag 是 `gh release view <tag>` / `upload <tag>` 的位置参数
+            assertPositionArg(args.tag, 'Release Tag');
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             let repoTarget = args.repo;
             if (!repoTarget) {
                 const meta = await executor.getRepoMetadata(cwd, sessionId);
@@ -105,6 +113,8 @@ export function createReleaseTool(executor) {
             }
             const repoArgs = ['-R', repoTarget];
             const runOpts = { cwd, sessionId };
+            // 说明来自本地文件时经 stdin 注入（`--notes-file -`）：绕开 Windows 约 32K 的命令行上限
+            const stdinPatch = (body) => (body.stdin === undefined ? {} : { stdin: body.stdin });
             switch (args.action) {
                 case 'list': {
                     // 显式 limit 优先；缺省回退 executor.defaultListLimit（上限 50 防止全量 Release 撑爆输出）
@@ -130,14 +140,18 @@ export function createReleaseTool(executor) {
                     if (Array.isArray(args.assets)) {
                         for (const a of args.assets) {
                             if (typeof a === 'string' && a.trim())
-                                createCmd.push(a);
+                                createCmd.push(assertPositionArg(a.trim(), '资产路径'));
                         }
                     }
                     if (args.title)
                         createCmd.push('--title', args.title);
                     // notes 与 generate_notes 可共存：gh 会在自动生成的说明前 prepend 手写正文
-                    if (args.notes)
-                        createCmd.push('--notes', args.notes);
+                    const notes = resolveBodySource({ inline: args.notes, file: args.notes_file }, 
+                    // maxChars: 0 —— Release 说明的 GitHub 上限比 Issue/评论正文（65,536）宽得多，
+                    // 套用正文口径会把合法的长发版说明先拦下来；这里只保留 4MB 字节护栏，
+                    // 真正超限由 GitHub 侧报错（错误信息带字段名，可定位）。
+                    { cwd, flag: '--notes', fileFlag: '--notes-file', inlineField: 'notes', fileField: 'notes_file', maxChars: 0 });
+                    createCmd.push(...notes.argv);
                     if (args.generate_notes !== false)
                         createCmd.push('--generate-notes');
                     if (args.draft === true)
@@ -146,7 +160,7 @@ export function createReleaseTool(executor) {
                         createCmd.push('--prerelease');
                     if (args.target)
                         createCmd.push('--target', args.target);
-                    const res = await executor.run(createCmd, runOpts);
+                    const res = await executor.run(createCmd, { ...runOpts, ...stdinPatch(notes) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: `Release ${args.tag} 创建成功`, url: res.rawOutput };
@@ -157,18 +171,12 @@ export function createReleaseTool(executor) {
                     if (!Array.isArray(args.assets) || args.assets.length === 0) {
                         throw new Error('upload 操作必须提供 assets（文件路径列表）');
                     }
-                    if (args.clobber === true && args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 高危操作拦截：你即将覆盖上传 Release ${args.tag} 的同名旧资产（clobber 模式）。`,
-                            impact: 'clobber 会先删除既有同名资产再上传；若上传中途失败，旧资产已丢失且无法恢复。',
-                            requiredAction: '如确认覆盖，请向用户核实并附加 `confirm: true` 重新调用。',
-                        };
-                    }
                     const uploadCmd = ['release', 'upload', args.tag, ...repoArgs];
                     for (const a of args.assets) {
+                        // 每个资产都是位置参数：`--clobber` 混进来会绕过 confirm 闸门覆盖删同名资产
+                        // （复核报告 C-01a 的复现路径），必须在拼 argv 时就拒掉。
                         if (typeof a === 'string' && a.trim())
-                            uploadCmd.push(a);
+                            uploadCmd.push(assertPositionArg(a.trim(), '资产路径'));
                     }
                     if (args.clobber === true)
                         uploadCmd.push('--clobber');
@@ -195,14 +203,6 @@ export function createReleaseTool(executor) {
                 case 'delete': {
                     if (!args.tag)
                         throw new Error('delete 操作必须提供 tag');
-                    if (args.confirm !== true) {
-                        return {
-                            status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 高危操作拦截：你即将删除 Release ${args.tag}${args.cleanup_tag ? ' 及其 Git Tag' : ''}。`,
-                            impact: '删除 Release 不可逆；若同时清理 Tag，引用该 Tag 的历史版本入口将全部失效。',
-                            requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
-                        };
-                    }
                     const delCmd = ['release', 'delete', args.tag, ...repoArgs, '--yes'];
                     if (args.cleanup_tag === true)
                         delCmd.push('--cleanup-tag');
@@ -215,5 +215,5 @@ export function createReleaseTool(executor) {
                     throw new Error(`未知的 Release 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/repo.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderRepoMarkdown } from '../renderers/markdown.js';
 import { extractReadmeImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
 function normalizeOutput(data) {
@@ -10,7 +11,7 @@ function normalizeOutput(data) {
     return { result: data !== undefined && data !== null ? data : '' };
 }
 export function createRepoTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_repo',
         description: '查看 GitHub 仓库元数据、同步 Fork 仓库主干 (sync) 与跨仓库检索代码。默认查询当前工作区关联的仓库。',
         parameters: {
@@ -72,8 +73,7 @@ export function createRepoTool(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);
             // 显式 limit 优先；缺省回退 executor.defaultListLimit（用户可在插件配置中调整）
             const limitStr = String(typeof args.limit === 'number' && args.limit > 0 ? args.limit : Math.min(executor.defaultListLimit ?? 10, 50));
             const runOpts = { cwd, sessionId };
@@ -331,5 +331,5 @@ export function createRepoTool(executor) {
                     throw new Error(`未知的 Repo 操作: ${args.action}`);
             }
         },
-    };
+    });
 }