dsh-github-flow 0.7.0 → 0.7.1

package/lib/tools/help.js

@@ -27,9 +27,10 @@ const KNOWLEDGE_BASE = {
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
 💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+📄 **长正文走文件，别塞进 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、Actions 三类卡片点击均可在线查看详情（Actions 为 job / step 树 + 按需失败日志），无需跳浏览器。
+🖥️ **可视化工作台**：最左侧 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 详细操作指南
 
@@ -52,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 详细操作指南
@@ -65,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'])\`
@@ -125,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 版本发布指南
@@ -134,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\`（旧资产删除后不可恢复）。
@@ -255,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 社区功能。`,
@@ -289,7 +301,7 @@ const KNOWLEDGE_BASE = {
 - **审一个 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')\` 完全一致。
+  - **写回**（默认关闭）: \`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\`：**不要据此判断「就这些失败」**。
@@ -452,6 +464,7 @@ const KNOWLEDGE_BASE = {
 - 人类侧在线查看（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 调用）
 

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

@@ -3,6 +3,7 @@ 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;
@@ -49,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',
@@ -125,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) {
@@ -230,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(','));
                     }
@@ -238,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 };
@@ -246,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);
@@ -260,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 };
@@ -287,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 };

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;

package/lib/tools/pr.js

@@ -4,6 +4,7 @@ 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;
@@ -41,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',
@@ -166,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) {
@@ -373,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）。
@@ -387,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
@@ -397,6 +407,12 @@ 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 路径一字不动（默认行为零变化，这是本改动的
@@ -406,7 +422,8 @@ export function createPrTool(executor) {
                     if (lineComments.length > 0) {
                         const res = await executor.createPrReview(cwd, args.repo, args.pr_number, {
                             event: args.review_decision,
-                            body: args.body,
+                            // createPrReview 侧按 trim 归一，空串与 undefined 等价，直接给权威正文即可
+                            body: body.text,
                             comments: lineComments,
                             commit_id: args.commit_id,
                         });
@@ -419,7 +436,7 @@ export function createPrTool(executor) {
                          * 已提交正文统计等价；而在工具层算不必让 executor 回传审计字段。
                          * 目的是让调用方一眼看到「这轮意见里有没有 P0」，而不是自己数。
                          */
-                        const severity = summarizeSeverity([args.body, ...lineComments.map((c) => (c && typeof c.body === 'string' ? c.body : ''))].filter((b) => typeof b === 'string' && b.trim()));
+                        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 已提交（行级评注降级为正文段落）`
@@ -452,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 };
@@ -509,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 };
@@ -521,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 };

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,6 +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;
@@ -36,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',
@@ -108,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 撑爆输出）
@@ -139,8 +146,12 @@ export function createReleaseTool(executor) {
                     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)
@@ -149,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 };

package/lib/tools/task.d.ts

@@ -53,6 +53,10 @@ export declare function createTaskTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            body_file: {
+                type: string;
+                description: string;
+            };
             comments: {
                 type: string;
                 items: {

package/lib/tools/task.js

@@ -16,6 +16,7 @@ import { wrapWithGate } from '../destructive.js';
 import { readReviewRules } from '../review-rules.js';
 import { extractFailureAnchors } from '../executor/failure-anchors.js';
 import { renderTaskMarkdown } from '../renderers/markdown.js';
+import { resolveBodySource } from './body-input.js';
 import { classifyCommits, extractFileAnchors, finalizeEnvelope, renderReleaseNotes, selectFilesByBudget, suggestVersion, } from '../task-primitives.js';
 /**
  * 把 `pr checks` 的 bucket/state 归并成四态计数。
@@ -92,7 +93,11 @@ export function createTaskTool(executor) {
                 },
                 body: {
                     type: 'string',
-                    description: 'review_pr 写回时的整体说明（缺省会被补 [P2] 严重度前缀）。',
+                    description: 'review_pr 写回时的整体说明（缺省会被补 [P2] 严重度前缀）。与 body_file 二选一。',
+                },
+                body_file: {
+                    type: 'string',
+                    description: '写回说明来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 body 二选一；长正文用本参数，无需把全文读进上下文。',
                 },
                 comments: {
                     type: 'array',
@@ -269,9 +274,11 @@ export function createTaskTool(executor) {
                 const envelope = built.envelope;
                 // 写回：只有显式 write + confirm（闸门已在 wrapWithGate 里挡过一次）才执行
                 if (args.write === true) {
+                    // 行级评注走 REST，没有 `--body-file` 可用——正文只能由插件读文件后塞进 JSON 请求体
+                    const reviewBody = resolveBodySource({ inline: args.body, file: args.body_file }, { cwd });
                     const res = await executor.createPrReview(cwd, repoTarget, prNumber, {
                         event: args.review_decision,
-                        body: args.body,
+                        body: reviewBody.text,
                         comments: Array.isArray(args.comments) ? args.comments : [],
                         commit_id: d.headRefOid,
                     });

package/lib/ui/commit-modal.js

@@ -1,3 +1,5 @@
+import { FileDiffModal } from './file-diff-modal.js';
+import { splitUnifiedPatch, findPatchSection, normalizeRenamePath } from './diff-utils.js';
 /**
  * 提交详情模态弹窗组件（与设置弹窗同构）
  */
@@ -8,14 +10,76 @@ export function CommitDetailModal(props) {
     var h = React.createElement;
     var [fetchedDetail, setFetchedDetail] = React.useState(null);
     var [fetchingDetail, setFetchingDetail] = React.useState(false);
+    /**
+     * 点某个文件后的 diff 预览状态。
+     *
+     * 为什么补丁要懒加载而不是随弹窗一起取：多数时候用户只想看提交说明，
+     * 大提交的整包 patch 可以到几百 KB；只在真的点开某个文件时才拉一次，且整个
+     * 弹窗生命周期内复用同一份 patch（点第二个文件零延迟）。
+     */
+    var [patchState, setPatchState] = React.useState(null);
+    var [patchLoading, setPatchLoading] = React.useState(false);
+    var [patchError, setPatchError] = React.useState(null);
+    var [selectedFile, setSelectedFile] = React.useState(null);
+    var loadPatch = function () {
+        if (patchState || patchLoading)
+            return;
+        setPatchLoading(true);
+        setPatchError(null);
+        var url = "/api/github/commit-diff?sha=" + encodeURIComponent(c.sha) + (props.cwd ? "&cwd=" + encodeURIComponent(props.cwd) : "");
+        fetch(url)
+            .then(function (r) {
+            if (r.status === 404) {
+                setPatchLoading(false);
+                setPatchError("后端未提供提交补丁接口 (404)。请重启 DSH 桌面主程序以载入最新对比引擎。");
+                return null;
+            }
+            return r.json().catch(function () { return null; });
+        })
+            .then(function (j) {
+            if (!j)
+                return;
+            setPatchLoading(false);
+            if (j.ok && j.data && typeof j.data.patch === "string") {
+                setPatchState({ patch: j.data.patch, truncated: Boolean(j.data.truncated) });
+            }
+            else {
+                setPatchError((j && j.error) || "获取提交补丁失败");
+            }
+        })
+            .catch(function (err) {
+            setPatchLoading(false);
+            setPatchError("网络请求异常：" + ((err && err.message) || "未知错误"));
+        });
+    };
+    var openFileDiff = function (f) {
+        setSelectedFile(f);
+        loadPatch();
+    };
     React.useEffect(function () {
         var onKeyDown = function (e) {
-            if (e.key === "Escape" || e.keyCode === 27)
+            if (e.key === "Escape" || e.keyCode === 27) {
+                // 逐层关闭：先收内层 diff 预览，再按一次才关整个提交详情
+                if (selectedFile) {
+                    setSelectedFile(null);
+                    return;
+                }
                 props.onClose();
+            }
         };
         window.addEventListener("keydown", onKeyDown);
         return function () { window.removeEventListener("keydown", onKeyDown); };
-    }, [props.onClose]);
+    }, [props.onClose, selectedFile]);
+    /**
+     * 换提交时清空上一份补丁与选中文件。
+     * 当前调用方在关闭时卸载组件（状态自然复位），但组件一旦被复用（不 key、不卸载），
+     * 残留的 patch 会把 A 提交的差异套到 B 提交的文件路径上——这类错配极难排查，先兜住。
+     */
+    React.useEffect(function () {
+        setPatchState(null);
+        setPatchError(null);
+        setSelectedFile(null);
+    }, [c.sha]);
     React.useEffect(function () {
         setFetchedDetail(null);
         if (c.body || c.stat)
@@ -39,6 +103,13 @@ export function CommitDetailModal(props) {
     var parsedStat = React.useMemo(() => {
         return effectiveStat && typeof parseGitStatText === "function" ? parseGitStatText(effectiveStat) : null;
     }, [effectiveStat]);
+    /**
+     * 切段结果必须缓存：大提交的整包 patch 可达 400k 字符，而本组件在弹窗生命周期里
+     * 会因 selectedFile / patchError 等状态多次重渲染——每次重渲染都重新切一遍是纯浪费。
+     */
+    var patchSections = React.useMemo(function () {
+        return patchState ? splitUnifiedPatch(patchState.patch) : [];
+    }, [patchState]);
     return h("div", {
         className: "dsh-github-modal-overlay",
         onClick: props.onClose,
@@ -142,6 +213,18 @@ export function CommitDetailModal(props) {
                 return h("div", {
                     key: idx,
                     className: "dsh-github-stat-row",
+                    // 可点击 + 可键盘操作：文件行是入口而不是纯展示，缺 aria/键盘会让
+                    // 只用 Tab 的人根本发现不了「能点开看 diff」
+                    role: "button",
+                    tabIndex: 0,
+                    "aria-label": "查看 " + f.path + " 的差异",
+                    onClick: function () { openFileDiff(f); },
+                    onKeyDown: function (e) {
+                        if (e.key === "Enter" || e.key === " " || e.keyCode === 13 || e.keyCode === 32) {
+                            e.preventDefault();
+                            openFileDiff(f);
+                        }
+                    },
                     style: {
                         display: "flex",
                         alignItems: "center",
@@ -151,8 +234,10 @@ export function CommitDetailModal(props) {
                         lineHeight: "1.4",
                         borderBottom: idx < parsedStat.files.length - 1 ? "1px solid var(--dsw-alias-border-subtle, rgba(0,0,0,0.06))" : "none",
                         gap: "8px",
+                        cursor: "pointer",
+                        userSelect: "none",
                     },
-                    title: f.path + (f.isBinary ? " (二进制文件)" : ` (+${f.additions}, -${f.deletions})`),
+                    title: f.path + (f.isBinary ? " (二进制文件)" : ` (+${f.additions}, -${f.deletions})`) + "\n点击查看该文件的代码改动",
                 }, h("div", {
                     style: {
                         fontFamily: "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace",
@@ -193,6 +278,7 @@ export function CommitDetailModal(props) {
                                 style: { display: "flex", gap: "1px", marginLeft: "2px", alignItems: "center" },
                             }, ...diffBlocks)
                             : null,
+                        h("span", { key: "chev", style: { opacity: 0.4, marginLeft: "2px", fontSize: "12px" }, "aria-hidden": "true" }, "›"),
                     ]));
             }))
             : h("pre", {
@@ -215,5 +301,23 @@ export function CommitDetailModal(props) {
         ? (fetchingDetail
             ? h("div", { style: { fontSize: "12px", opacity: 0.7, padding: "8px 0" } }, "⏳ 正在获取详细变更说明…")
             : h("div", { style: { fontSize: "11px", opacity: 0.6, fontStyle: "italic", padding: "6px 0" } }, "（该提交未包含多行正文；重启 DSH 桌面端可同步最新格式并直接呈现变更统计）"))
-        : null)));
+        : null)), 
+    // 内层 diff 预览：作为 overlay 的兄弟节点而非 dialog 的子节点，
+    // 这样它是独立的一层遮罩（zIndex 更高），点遮罩只关它自己
+    selectedFile
+        ? h(FileDiffModal, {
+            file: selectedFile,
+            cwd: props.cwd,
+            // 传字符串而不是 null：null 会被组件当成「未提供正文 → 自己去拉未提交 diff」
+            diffText: (findPatchSection(patchSections, normalizeRenamePath(selectedFile.path)) || { text: "" }).text,
+            subtitle: String(c.fullSha || c.sha || "").slice(0, 7),
+            loading: patchLoading,
+            error: patchError,
+            note: patchState && patchState.truncated
+                ? "该提交差异过大，预览只覆盖补丁被截断前的文件；其余文件请用命令行查看。"
+                : null,
+            zIndex: 100001,
+            onClose: function () { setSelectedFile(null); },
+        })
+        : null);
 }