dsh-github-flow 0.7.0 → 0.7.1

package/lib/executor.d.ts

@@ -80,6 +80,13 @@ export declare class GhExecutor {
      *
      * 解析顺序：显式 cwd（原样透传，含不存在的情况，与旧行为一致）→ session 反查 →
      * process.cwd()。三级都拿不到时才回到进程目录，与 s5 之前的兜底完全一致。
+     *
+     * ⚠️ `agent.id` 必须参与反查：DSH 真实的 ToolRunContext（宿主 tools 服务的
+     * `ToolExecutionInput`）只有 `agent: { id: SessionId }`，**既没有 cwd 也没有 sessionId**。
+     * 早先只认 `sessionId` / `session.id` / 环境变量，于是这一级在桌面端永远不触发，
+     * 所有工具退化到宿主进程的 process.cwd()（实测是 profile 目录）——表现为 `repo`
+     * 留空时无法自动识别仓库、`body_file` 这类相对路径参数被解析到错误目录。
+     * 这里改成「候选逐个试到命中为止」而非短路：任一来源能反查到工作区就返回。
      */
     resolveExecScope(execContext?: {
         cwd?: string;
@@ -87,6 +94,9 @@ export declare class GhExecutor {
         session?: {
             id?: string;
         };
+        agent?: {
+            id?: string;
+        };
     }): {
         cwd: string;
         sessionId?: string;
@@ -204,6 +214,44 @@ export declare class GhExecutor {
      * 语法都不可能通过校验）。输出为 git show --stat 原文（含文件变更统计）。
      */
     getGitCommitDetail(cwd: string | undefined, sha: string): Promise<string | null>;
+    /**
+     * 某次提交的完整补丁（提交详情弹窗里点单个文件时，前端按 `diff --git` 切分后取对应段）。
+     *
+     * 为什么整包取一次，而不是按文件逐个 `git show <sha> -- <path>`：
+     * 用户点哪个文件是未知的，逐个文件来一次就是 N 次进程启动（Windows 上每次几十毫秒），
+     * 同一提交内多个文件还要重复解析。一次拿全量交给前端切分，把延迟从「每次点击」
+     * 摊到「打开弹窗一次」。
+     *
+     * 白名单纪律延续 getGitCommitDetail：sha 先过 `/^[0-9a-f]{4,40}$/i` 才拼接，
+     * 值域锁死为纯十六进制，注入面为零；命令形态整体常量硬编码。各选项为什么存在：
+     * - `--format=`：清空提交头。默认输出前半截是 commit/Author/Date/message，
+     *   前端按 `diff --git` 切片时会把这段脏头当成第一个文件的内容；
+     * - `--no-ext-diff`：用户一旦配置 `diff.external`，git 会去执行任意外部程序。
+     *   这是本地服务，不能因为一条读请求就把用户的外部工具跑起来；
+     * - `--no-color`：用户若设了 `color.ui=always`，patch 里会混进 ANSI 转义序列，
+     *   前端按行首 `+`/`-` 判定增删行的逻辑会直接判错；
+     * - `core.quotepath=false`：quotepath 为 true（git 内建默认）时非 ASCII 路径被转义成
+     *   `\344\270\255` 并包上双引号（实测），前端按 `a/` 前缀切出的文件名与真实路径对不上；
+     * - `--src-prefix=a/ --dst-prefix=b/`：用户全局开 `diff.noprefix=true` 时路径没有
+     *   `a/`/`b/` 前缀，切分与还原文件名的逻辑全部错位，这里强制钉死前缀；
+     * - 末尾 `--`：关死 sha 之后的参数位，避免可被解释成 pathspec 的输入混进命令。
+     *
+     * 体积护栏：大提交的 patch 可达数十 MB，整包透传给 WebView 会卡死渲染。超过
+     * 400_000 字符时在**最后一个 `\ndiff --git ` 边界**处截断——绝不切在 hunk 中间，
+     * 否则前端拿到半截 hunk 会渲染出错行；只有找不到边界（极端单文件巨型 diff）
+     * 才硬切到上限，此时 truncated 标记让前端给出「已截断」提示。
+     *
+     * 空 patch 是正常结果而非错误：合并提交默认不展开 diff、空提交也没有内容，
+     * 两者都返回 ok:true + 空字符串，由 UI 决定怎么展示。
+     */
+    getCommitDiff(cwd: string | undefined, sha: string): Promise<{
+        ok: boolean;
+        sha?: string;
+        patch?: string;
+        chars?: number;
+        truncated?: boolean;
+        error?: string;
+    }>;
     /**
      * 纯本地读取工作区的所有 Git 分支（按提交时间倒序）。
      * 包含当前 HEAD 分支标记、关联 upstream、最新提交简述与相对时间。

package/lib/executor.js

@@ -236,20 +236,32 @@ export class GhExecutor {
      *
      * 解析顺序：显式 cwd（原样透传，含不存在的情况，与旧行为一致）→ session 反查 →
      * process.cwd()。三级都拿不到时才回到进程目录，与 s5 之前的兜底完全一致。
+     *
+     * ⚠️ `agent.id` 必须参与反查：DSH 真实的 ToolRunContext（宿主 tools 服务的
+     * `ToolExecutionInput`）只有 `agent: { id: SessionId }`，**既没有 cwd 也没有 sessionId**。
+     * 早先只认 `sessionId` / `session.id` / 环境变量，于是这一级在桌面端永远不触发，
+     * 所有工具退化到宿主进程的 process.cwd()（实测是 profile 目录）——表现为 `repo`
+     * 留空时无法自动识别仓库、`body_file` 这类相对路径参数被解析到错误目录。
+     * 这里改成「候选逐个试到命中为止」而非短路：任一来源能反查到工作区就返回。
      */
     resolveExecScope(execContext) {
-        const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+        const candidates = [
+            execContext?.sessionId,
+            execContext?.session?.id,
+            execContext?.agent?.id,
+            process.env.DSH_SESSION_ID,
+        ].filter((id) => typeof id === 'string' && id.length > 0);
         // 1) 显式 cwd 原样透传：这是唯一事实源，不做存在性替换，也不许被会话反查覆盖
         if (execContext?.cwd)
-            return { cwd: execContext.cwd, sessionId };
-        // 2) 按会话反查真实工作区（旧实现被 process.cwd() 短路掉的那一级）
-        if (sessionId) {
+            return { cwd: execContext.cwd, sessionId: candidates[0] };
+        // 2) 按会话反查真实工作区：候选之间是或关系，任一击即返回（查出空就试下一个）
+        for (const sessionId of candidates) {
             const fromSession = findWorkspacePathBySession(sessionId);
             if (fromSession)
                 return { cwd: fromSession, sessionId };
         }
         // 3) 兜底到进程目录。**不**调用 findMostRecentWorkspacePath()
-        return { cwd: process.cwd(), sessionId };
+        return { cwd: process.cwd(), sessionId: candidates[0] };
     }
     /**
      * 安全执行 gh 命令
@@ -810,6 +822,70 @@ export class GhExecutor {
             return null;
         }
     }
+    /**
+     * 某次提交的完整补丁（提交详情弹窗里点单个文件时，前端按 `diff --git` 切分后取对应段）。
+     *
+     * 为什么整包取一次，而不是按文件逐个 `git show <sha> -- <path>`：
+     * 用户点哪个文件是未知的，逐个文件来一次就是 N 次进程启动（Windows 上每次几十毫秒），
+     * 同一提交内多个文件还要重复解析。一次拿全量交给前端切分，把延迟从「每次点击」
+     * 摊到「打开弹窗一次」。
+     *
+     * 白名单纪律延续 getGitCommitDetail：sha 先过 `/^[0-9a-f]{4,40}$/i` 才拼接，
+     * 值域锁死为纯十六进制，注入面为零；命令形态整体常量硬编码。各选项为什么存在：
+     * - `--format=`：清空提交头。默认输出前半截是 commit/Author/Date/message，
+     *   前端按 `diff --git` 切片时会把这段脏头当成第一个文件的内容；
+     * - `--no-ext-diff`：用户一旦配置 `diff.external`，git 会去执行任意外部程序。
+     *   这是本地服务，不能因为一条读请求就把用户的外部工具跑起来；
+     * - `--no-color`：用户若设了 `color.ui=always`，patch 里会混进 ANSI 转义序列，
+     *   前端按行首 `+`/`-` 判定增删行的逻辑会直接判错；
+     * - `core.quotepath=false`：quotepath 为 true（git 内建默认）时非 ASCII 路径被转义成
+     *   `\344\270\255` 并包上双引号（实测），前端按 `a/` 前缀切出的文件名与真实路径对不上；
+     * - `--src-prefix=a/ --dst-prefix=b/`：用户全局开 `diff.noprefix=true` 时路径没有
+     *   `a/`/`b/` 前缀，切分与还原文件名的逻辑全部错位，这里强制钉死前缀；
+     * - 末尾 `--`：关死 sha 之后的参数位，避免可被解释成 pathspec 的输入混进命令。
+     *
+     * 体积护栏：大提交的 patch 可达数十 MB，整包透传给 WebView 会卡死渲染。超过
+     * 400_000 字符时在**最后一个 `\ndiff --git ` 边界**处截断——绝不切在 hunk 中间，
+     * 否则前端拿到半截 hunk 会渲染出错行；只有找不到边界（极端单文件巨型 diff）
+     * 才硬切到上限，此时 truncated 标记让前端给出「已截断」提示。
+     *
+     * 空 patch 是正常结果而非错误：合并提交默认不展开 diff、空提交也没有内容，
+     * 两者都返回 ok:true + 空字符串，由 UI 决定怎么展示。
+     */
+    async getCommitDiff(cwd, sha) {
+        if (typeof sha !== 'string' || !/^[0-9a-f]{4,40}$/i.test(sha)) {
+            return { ok: false, error: `非法的提交 SHA: "${sha}"（只允许十六进制短/全 SHA）` };
+        }
+        try {
+            const { stdout } = await execFileAsync('git', [
+                '-c', 'core.quotepath=false',
+                'show',
+                '--format=',
+                '--no-color',
+                '--no-ext-diff',
+                '--src-prefix=a/',
+                '--dst-prefix=b/',
+                sha,
+                '--',
+            ], { cwd: cwd || undefined, timeout: 8_000, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+            const raw = String(stdout);
+            const MAX = 400_000;
+            let patch = raw;
+            let truncated = false;
+            if (patch.length > MAX) {
+                truncated = true;
+                const boundary = patch.lastIndexOf('\ndiff --git ', MAX);
+                patch = boundary > 0 ? patch.slice(0, boundary) : patch.slice(0, MAX);
+            }
+            return { ok: true, sha, patch, chars: patch.length, truncated };
+        }
+        catch (err) {
+            // 优先回 stderr：sha 不存在（bad object）、不是本仓库等真实原因只在 stderr 里，
+            // execFile 的 message 只是 "Command failed: git show …" 的包装
+            const stderr = typeof err?.stderr === 'string' ? err.stderr.trim() : '';
+            return { ok: false, error: stderr || err?.message || '获取提交补丁失败' };
+        }
+    }
     /**
      * 纯本地读取工作区的所有 Git 分支（按提交时间倒序）。
      * 包含当前 HEAD 分支标记、关联 upstream、最新提交简述与相对时间。

package/lib/tools/agent-task.d.ts

@@ -22,6 +22,10 @@ export declare function createAgentTaskTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            prompt_file: {
+                type: string;
+                description: string;
+            };
             base_branch: {
                 type: string;
                 description: string;

package/lib/tools/agent-task.js

@@ -1,5 +1,6 @@
 import { wrapWithGate } from '../destructive.js';
 import { renderAgentTaskMarkdown } from '../renderers/markdown.js';
+import { resolveBodySource } from './body-input.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -32,7 +33,11 @@ export function createAgentTaskTool(executor) {
                 },
                 prompt: {
                     type: 'string',
-                    description: '任务描述正文或编码指令（create 动作必需，如 "为用户模块增加单元测试"）。',
+                    description: '任务描述正文或编码指令（create 动作必需，如 "为用户模块增加单元测试"）。与 prompt_file 二选一。',
+                },
+                prompt_file: {
+                    type: 'string',
+                    description: '任务描述来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 prompt 二选一。',
                 },
                 base_branch: {
                     type: 'string',
@@ -63,6 +68,8 @@ export function createAgentTaskTool(executor) {
             const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const repoArgs = args.repo ? ['-R', args.repo] : [];
             const runOpts = { cwd, sessionId };
+            // 任务描述来自文件时经 stdin 注入（`--from-file -`）：绕开 Windows 约 32K 的命令行上限
+            const stdinPatch = (body) => (body.stdin === undefined ? {} : { stdin: body.stdin });
             switch (args.action) {
                 case 'list': {
                     const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
@@ -111,15 +118,21 @@ export function createAgentTaskTool(executor) {
                     return taskData || { id: cleanId };
                 }
                 case 'create': {
-                    if (!args.prompt || typeof args.prompt !== 'string' || !args.prompt.trim()) {
-                        throw new Error('create 操作必须提供 prompt（任务描述正文或编码指令）');
+                    // 内联 prompt 继续走位置参数：它的 argv 必须与改造前逐字节一致，只有文件来源才切
+                    // `--from-file -`。gh agent-task 是 preview 命令，该 flag 形态可能随上游变化。
+                    const inlinePrompt = typeof args.prompt === 'string' ? args.prompt.trim() : '';
+                    const body = resolveBodySource({ inline: inlinePrompt, file: args.prompt_file }, { cwd, fileFlag: '--from-file', inlineField: 'prompt', fileField: 'prompt_file' });
+                    if (body.chars === 0) {
+                        throw new Error('create 操作必须提供 prompt 或 prompt_file（任务描述正文或编码指令）');
                     }
-                    const createCmd = ['agent-task', 'create', args.prompt.trim(), ...repoArgs];
+                    const createCmd = body.fromFile
+                        ? ['agent-task', 'create', ...repoArgs, ...body.argv]
+                        : ['agent-task', 'create', inlinePrompt, ...repoArgs];
                     if (args.base_branch)
                         createCmd.push('-b', args.base_branch.trim());
                     if (args.custom_agent)
                         createCmd.push('-a', args.custom_agent.trim());
-                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return {

package/lib/tools/api.d.ts

@@ -22,6 +22,10 @@ export declare function createApiTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            input_file: {
+                type: string;
+                description: string;
+            };
             raw: {
                 type: string;
                 description: string;

package/lib/tools/api.js

@@ -1,4 +1,5 @@
 import { wrapWithGate } from '../destructive.js';
+import { resolveBodySource } from './body-input.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -22,7 +23,7 @@ export function createApiTool(executor) {
                 method: {
                     type: 'string',
                     enum: ['GET', 'POST', 'PATCH', 'DELETE'],
-                    description: 'HTTP 方法，默认为 GET（GraphQL 端点默认 POST）。',
+                    description: 'HTTP 方法，默认为 GET（GraphQL 端点或提供 input_file 时默认 POST）。',
                 },
                 jq: {
                     type: 'string',
@@ -30,7 +31,11 @@ export function createApiTool(executor) {
                 },
                 fields: {
                     type: 'object',
-                    description: '请求参数或请求体键值对。所有值按字面字符串（gh -f）发送，不做布尔/数字类型转换；嵌套对象请先在端点里用 JSON 字段或改用 raw 模式。',
+                    description: '请求参数或请求体键值对。所有值按字面字符串（gh -f）发送，不做布尔/数字类型转换；嵌套结构无法作为表单参数，请把完整请求体写入本地文件后用 input_file 传入。',
+                },
+                input_file: {
+                    type: 'string',
+                    description: '请求体来源：本地文件路径（相对路径按当前工作区解析）。映射 gh api --input，文件内容原样作为请求体（GraphQL 需写 {"query":...} 形式的 JSON）；与 fields 并用时 gh 会把 fields 追加为查询参数。',
                 },
                 raw: {
                     type: 'boolean',
@@ -72,11 +77,28 @@ export function createApiTool(executor) {
                 throw new Error(`endpoint 不能以 - 开头（会被 gh 当作命令行 flag）："${endpoint}"。`);
             }
             const cmd = ['api', endpoint];
+            /*
+             * 请求体可来自本地文件（`--input -` + stdin）。
+             *
+             * 只接文件、不接内联：`fields` 就是内联通道，二者按契约可共存（gh 把 fields 追加为
+             * 查询参数），所以这里不传 inline——传了会被 helper 判成互斥而误拒合法调用。
+             * `maxChars: 0`：`--input` 的请求体是 JSON/GraphQL，不受 GitHub「正文 65536 字符」
+             * 口径约束，套用正文上限会把合法的大 mutation 拦死。
+             */
+            const inputFileGiven = typeof args.input_file === 'string' && args.input_file.trim().length > 0;
+            const body = resolveBodySource({ file: args.input_file }, { cwd, flag: '--input', fileFlag: '--input', inlineField: 'fields', fileField: 'input_file', maxChars: 0 });
+            // 空文件若静默放过，发出去的是一个没有请求体的请求——服务端报的错与真实原因无关，极难排查
+            if (inputFileGiven && body.chars === 0) {
+                throw new Error(`input_file 内容为空：指向的文件没有任何内容（"${args.input_file}"）。请写入完整请求体后重试，或改用 fields。`);
+            }
+            // 请求体来自文件时经 stdin 注入（`--input -`）：绕开 Windows 约 32K 的命令行上限
+            const stdinPatch = (b) => (b.stdin === undefined ? {} : { stdin: b.stdin });
             // gh api 默认在提供 -f/-F 时会自动将 HTTP 方法隐式切换为 POST。
             // 若调用方未指定 method，且 endpoint 不是以 graphql 开头，则按契约默认为 GET。
             // 必须显式传入 -X，防止带有 fields 参数的 GET 请求被 gh 自动改写为 POST 导致 422 报错。
             const isGraphql = endpoint.toLowerCase().startsWith('graphql');
-            const method = args.method || (isGraphql ? 'POST' : 'GET');
+            // 带了 `--input` 却不给 -X 时，gh 仍按 GET 发出，请求体会被服务端静默丢弃——有正文即 POST
+            const method = args.method || (isGraphql || body.chars > 0 ? 'POST' : 'GET');
             cmd.push('-X', method);
             if (args.jq) {
                 cmd.push('--jq', args.jq);
@@ -96,15 +118,17 @@ export function createApiTool(executor) {
                         continue;
                     if (typeof v === 'object') {
                         // 不把嵌套结构 JSON.stringify 后塞进 -F：gh 侧解析结果不可预期，且会静默产出错误请求体。
-                        // 宁可显式报错，让调用方改用 raw 模式或把结构放进端点自身的 JSON 字段。
-                        throw new Error(`github_api 的字段 "${k}" 是嵌套结构，无法作为表单参数发送。请改用 raw 模式传原始 JSON 请求体，或先把该结构序列化后作为字符串字段传入。`);
+                        // 宁可显式报错，让调用方改用 input_file 传完整请求体，或把结构序列化后作为字符串字段。
+                        throw new Error(`github_api 的字段 "${k}" 是嵌套结构，无法作为表单参数发送。请把完整请求体写入本地 JSON 文件后用 input_file 传入（映射 gh api --input），或先把该结构序列化后作为字符串字段传入。`);
                     }
                     // 用 -f（字面字符串）而非 -F：-F 会做 "true"→布尔、"1"→数字的类型转换，
                     // 导致字符串请求体被悄悄改写，是跨 fork 提 PR 等场景失败的常见根因。
                     cmd.push('-f', `${k}=${String(v)}`);
                 }
             }
-            const res = await executor.run(cmd, { cwd, sessionId, rawText: args.raw === true });
+            // 与 fields 并用时 gh 会把 fields 追加为查询参数，两者不互斥
+            cmd.push(...body.argv);
+            const res = await executor.run(cmd, { cwd, sessionId, rawText: args.raw === true, ...stdinPatch(body) });
             if (!res.ok)
                 throw new Error(res.error);
             return normalizeOutput(res.data !== undefined ? res.data : res.rawOutput);

package/lib/tools/body-input.d.ts

@@ -0,0 +1,58 @@
+/**
+ * GitHub 正文上限（Issue/PR/评论/讨论统一口径 65,536 字符）。
+ * 抽成常量而不是散落字面量：这是上游约束，将来调整只改一处。
+ */
+export declare const GITHUB_BODY_MAX_CHARS = 65536;
+/**
+ * 单个正文文件的字节硬上限（4MB）。
+ * 字符上限只管正文语义，管不住「模型指了一个 200MB 日志文件」——先按字节拦住，
+ * 避免 readFileSync 把整个文件拉进内存再判定。
+ */
+export declare const BODY_FILE_MAX_BYTES: number;
+/** 入参归一化的产出：argv 片段 + 需要注入的 stdin + 权威文本 */
+export interface BodySource {
+    /** 交给 gh 的 argv 片段：`[]` | `[flag, text]` | `[fileFlag, '-']` */
+    argv: string[];
+    /** `[fileFlag, '-']` 时需要经 stdin 注入的正文；其余情况为 undefined */
+    stdin?: string;
+    /** 权威正文（REST/GraphQL 通道直接用它；调用方做必填判定也看它） */
+    text: string;
+    /** `text` 的字符数（按 UTF-16 单元近似 GitHub 的字符口径） */
+    chars: number;
+    fromFile: boolean;
+    /** 文件来源时解析后的绝对路径（仅用于回执与错误诊断） */
+    file?: string;
+}
+export interface BodySourceOptions {
+    /** 相对路径的解析基准（工具层传 `executor.resolveExecScope` 得到的工作区） */
+    cwd: string;
+    /** 内联 flag，缺省 `--body`（discussion 用 `-b`） */
+    flag?: string;
+    /** 文件 flag，缺省 `--body-file`（release 用 `--notes-file`，api/agent-task 用各自 flag） */
+    fileFlag?: string;
+    /** 内联字段名，仅用于错误文案（缺省 `body`） */
+    inlineField?: string;
+    /** 文件字段名，仅用于错误文案（缺省 `body_file`） */
+    fileField?: string;
+    /** 无正文时仍下发 `[flag, '']`：create 需要它保持非交互（否则 gh 会打开编辑器） */
+    keepEmptyInline?: boolean;
+    /** 字符上限覆盖；传 0 关闭字符校验（`gh api --input` 的请求体不受正文口径约束） */
+    maxChars?: number;
+}
+/**
+ * 解析正文来源。
+ *
+ * 语义表（与计划文档一致，调用方不再各自二次决策）：
+ * | 输入 | argv | stdin |
+ * | --- | --- | --- |
+ * | `file` 有值且文件非空 | `[fileFlag, '-']` | 文件正文 |
+ * | `file` 有值但文件为空 | 同「都为空」 | — |
+ * | `inline` 非空 | `[flag, inline]` | — |
+ * | 都为空 + keepEmptyInline | `[flag, '']` | — |
+ * | 都为空 | `[]` | — |
+ * | 两者都非空 | 抛错（不做静默优先级） | — |
+ */
+export declare function resolveBodySource(input: {
+    inline?: unknown;
+    file?: unknown;
+}, options?: BodySourceOptions): BodySource;

package/lib/tools/body-input.js

@@ -0,0 +1,123 @@
+/**
+ * 「正文/长文本来自本地文件」的统一入参解析（纯函数，零 gh 依赖）。
+ *
+ * 为什么需要它：Agent 的典型工作流是**先把报告写成 md 文件**，再提交成 Issue / PR 评论 /
+ * 讨论 / 发版说明。改造前这些入参只有字符串 `body`，模型只能把整篇正文搬进参数——
+ * 既烧上下文，又会在 Windows 约 32K 的命令行上限处炸掉（`E2BIG/EINVAL`，错误还很难懂）。
+ * 于是 Agent 会绕开插件直接用 `gh issue create -F report.md`，插件的确认闸门/错误分类/渲染
+ * 全部被跳过。
+ *
+ * 为什么不让 gh 自己去读文件（`--body-file <path>`）：`pr review` 的行级评注走 REST
+ * （`POST /pulls/{n}/reviews`），那条通道根本没有 flag，只能插件侧读文件后塞 JSON。
+ * 两套通道各写一份，必然漂移成「带 comments 时 body_file 静默失效」。因此统一为：
+ * **插件读一次文件** →
+ *   - CLI 通道：`[fileFlag, '-']` + `stdin`（`--body-file -` 由 gh 读 stdin，无 argv 长度上限）；
+ *   - REST/GraphQL 通道：直接用 `text`。
+ *
+ * 兼容性纪律：内联来源的 argv 必须与本模块引入前**逐字节一致**（`[flag, text]`），
+ * 新通道只在「传了 `*_file`」时才改变 argv。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * GitHub 正文上限（Issue/PR/评论/讨论统一口径 65,536 字符）。
+ * 抽成常量而不是散落字面量：这是上游约束，将来调整只改一处。
+ */
+export const GITHUB_BODY_MAX_CHARS = 65_536;
+/**
+ * 单个正文文件的字节硬上限（4MB）。
+ * 字符上限只管正文语义，管不住「模型指了一个 200MB 日志文件」——先按字节拦住，
+ * 避免 readFileSync 把整个文件拉进内存再判定。
+ */
+export const BODY_FILE_MAX_BYTES = 4 * 1024 * 1024;
+/** 严格 UTF-8 解码器：GBK/ANSI 存的中文 md 会抛错，而不是静默产出乱码 */
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+function emptyResult(flag, keepEmptyInline) {
+    return { argv: keepEmptyInline ? [flag, ''] : [], text: '', chars: 0, fromFile: false };
+}
+function inlineResult(flag, text) {
+    return { argv: [flag, text], text, chars: text.length, fromFile: false };
+}
+/**
+ * 解析正文来源。
+ *
+ * 语义表（与计划文档一致，调用方不再各自二次决策）：
+ * | 输入 | argv | stdin |
+ * | --- | --- | --- |
+ * | `file` 有值且文件非空 | `[fileFlag, '-']` | 文件正文 |
+ * | `file` 有值但文件为空 | 同「都为空」 | — |
+ * | `inline` 非空 | `[flag, inline]` | — |
+ * | 都为空 + keepEmptyInline | `[flag, '']` | — |
+ * | 都为空 | `[]` | — |
+ * | 两者都非空 | 抛错（不做静默优先级） | — |
+ */
+export function resolveBodySource(input, options = { cwd: process.cwd() }) {
+    const flag = options.flag ?? '--body';
+    const fileFlag = options.fileFlag ?? '--body-file';
+    const inlineField = options.inlineField ?? 'body';
+    const fileField = options.fileField ?? 'body_file';
+    const maxChars = options.maxChars ?? GITHUB_BODY_MAX_CHARS;
+    const rawInline = input.inline;
+    if (rawInline !== undefined && rawInline !== null && typeof rawInline !== 'string') {
+        throw new Error(`${inlineField} 必须是字符串。`);
+    }
+    // 不做 trim：内联正文要原样下发，保持与改造前逐字节一致
+    const inline = typeof rawInline === 'string' ? rawInline : '';
+    const rawFile = input.file;
+    if (rawFile === undefined || rawFile === null) {
+        return inline.length > 0 ? inlineResult(flag, inline) : emptyResult(flag, options.keepEmptyInline);
+    }
+    if (typeof rawFile !== 'string') {
+        throw new Error(`${fileField} 必须是本地文件路径字符串（绝对路径或相对当前工作区的路径）。`);
+    }
+    const fileInput = rawFile.trim();
+    // 空串视同未提供：调用方（含契约测试的样例表）用一个空串表达「这条路不走」
+    if (!fileInput) {
+        return inline.length > 0 ? inlineResult(flag, inline) : emptyResult(flag, options.keepEmptyInline);
+    }
+    // 二选一而非优先级：模型拿到一次明确失败，远好过「不知道哪份真正生效」
+    if (inline.length > 0) {
+        throw new Error(`${inlineField} 与 ${fileField} 同时提供：请二选一（长正文用 ${fileField}，短文本用 ${inlineField}）。`);
+    }
+    const abs = path.isAbsolute(fileInput) ? fileInput : path.resolve(options.cwd, fileInput);
+    let stat;
+    try {
+        stat = fs.statSync(abs);
+    }
+    catch {
+        throw new Error(`${fileField} 指向的文件不存在: "${abs}"（输入: "${fileInput}"）。`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`${fileField} 必须是普通文件，当前指向的不是文件: "${abs}"。`);
+    }
+    if (stat.size > BODY_FILE_MAX_BYTES) {
+        // 用字节数报错而不是 toFixed(1) 的 MB：4MB+1 字节会被四舍五入显示成「4.0MB 超过 4MB」，
+        // 看上去像插件算错了，反而增加排查成本
+        throw new Error(`${fileField} 文件过大: ${stat.size} 字节，超过 ${BODY_FILE_MAX_BYTES} 字节（4MB）上限。`);
+    }
+    const buf = fs.readFileSync(abs);
+    // 二进制先判、再解码：PNG 之类在 UTF-8 解码阶段会报「不是合法 UTF-8」并给出 GBK 另存建议，
+    // 对二进制文件是误导；NUL 字节是更准确的判据（文本文件不会有）
+    if (buf.includes(0)) {
+        throw new Error(`${fileField} 内容是二进制（含 NUL 字节），不能作为正文: "${abs}"。`);
+    }
+    let text;
+    try {
+        text = strictUtf8.decode(buf);
+    }
+    catch {
+        throw new Error(`${fileField} 不是合法 UTF-8 文本: "${abs}"。Windows 上常见 GBK/ANSI 编码，请另存为 UTF-8 后重试。`);
+    }
+    // 解码头本身会剥 BOM（TextDecoder 的 ignoreBOM 默认 false）；这里显式再剥一次是防御：
+    // 一旦有人把上面改成 ignoreBOM: true，正文首字符就会变成零宽 BOM 字符
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
+    const chars = text.length;
+    if (maxChars > 0 && chars > maxChars) {
+        throw new Error(`${fileField} 正文过长: ${chars} 字符，超过上限 ${maxChars} 字符。请拆分或精简后再提交。`);
+    }
+    // 空文件不进 stdin 通道：不依赖 gh 对空 stdin 的处理，语义与「没正文」完全一致
+    if (chars === 0)
+        return emptyResult(flag, options.keepEmptyInline);
+    return { argv: [fileFlag, '-'], stdin: text, text, chars, fromFile: true, file: abs };
+}

package/lib/tools/discussion.d.ts

@@ -26,6 +26,10 @@ export declare function createDiscussionTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            body_file: {
+                type: string;
+                description: string;
+            };
             category: {
                 type: string;
                 description: string;

package/lib/tools/discussion.js

@@ -1,5 +1,6 @@
 import { wrapWithGate } from '../destructive.js';
 import { renderDiscussionMarkdown } from '../renderers/markdown.js';
+import { resolveBodySource } from './body-input.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -37,7 +38,11 @@ export function createDiscussionTool(executor) {
                 },
                 body: {
                     type: 'string',
-                    description: '讨论正文或评论正文（create, comment 必需，edit 动作修改正文时可选）。',
+                    description: '讨论正文或评论正文（create, comment 必需，edit 动作修改正文时可选）。与 body_file 二选一。',
+                },
+                body_file: {
+                    type: 'string',
+                    description: '正文来源：本地 Markdown 文件路径（相对路径按当前工作区解析）。与 body 二选一；长正文用本参数，无需把全文读进上下文。',
                 },
                 category: {
                     type: 'string',
@@ -78,6 +83,14 @@ export function createDiscussionTool(executor) {
             const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const repoArgs = args.repo ? ['-R', args.repo] : [];
             const runOpts = { cwd, sessionId };
+            // 正文来自本地文件时经 stdin 注入（`--body-file -`）：绕开 Windows 约 32K 的命令行上限
+            const stdinPatch = (body) => (body.stdin === undefined ? {} : { stdin: body.stdin });
+            /*
+             * 内联正文沿用改造前的 trim 口径（旧代码是 `-b args.body.trim()`）：discussion 历史上
+             * 就按去空白下发，改成原样会动到既有调用方的 argv。文件来源不 trim——那是用户排好版的
+             * Markdown，首尾空行/缩进可能有意义，strip 掉等于替用户改稿。
+             */
+            const trimInline = (v) => (typeof v === 'string' ? v.trim() : v);
             switch (args.action) {
                 case 'list': {
                     const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(args.limit, 100) : 30;
@@ -126,8 +139,10 @@ export function createDiscussionTool(executor) {
                     if (!args.title || typeof args.title !== 'string' || !args.title.trim()) {
                         throw new Error('create 操作必须提供 title（讨论标题）');
                     }
-                    if (!args.body || typeof args.body !== 'string' || !args.body.trim()) {
-                        throw new Error('create 操作必须提供 body（讨论正文）');
+                    const body = resolveBodySource({ inline: trimInline(args.body), file: args.body_file }, { cwd, flag: '-b' });
+                    // 判空只看解析后的权威正文：文件来源时 args.body 恒为空，拿它判定会误杀
+                    if (body.chars === 0) {
+                        throw new Error('create 操作必须提供 body 或 body_file（讨论正文）');
                     }
                     if (!args.category || typeof args.category !== 'string' || !args.category.trim()) {
                         throw new Error('create 操作必须提供 category（讨论分类，例如 "General"、"Q&A"、"Ideas"）');
@@ -135,11 +150,11 @@ export function createDiscussionTool(executor) {
                     const createCmd = [
                         'discussion', 'create',
                         '-t', args.title.trim(),
-                        '-b', args.body.trim(),
+                        ...body.argv,
                         '-c', args.category.trim(),
                         ...repoArgs,
                     ];
-                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    const res = await executor.run(createCmd, { ...runOpts, rawText: true, timeoutMs: 60_000, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return {
@@ -151,15 +166,15 @@ export function createDiscussionTool(executor) {
                     if (!args.discussion_number || typeof args.discussion_number !== 'number') {
                         throw new Error('edit 操作必须提供 discussion_number（讨论数字编号）');
                     }
-                    if (!args.title && !args.body) {
+                    const body = resolveBodySource({ inline: trimInline(args.body), file: args.body_file }, { cwd, flag: '-b' });
+                    if (!args.title && body.chars === 0) {
                         throw new Error('edit 操作至少需提供 title 或 body 中的一项进行修改');
                     }
                     const editCmd = ['discussion', 'edit', String(args.discussion_number), ...repoArgs];
                     if (args.title)
                         editCmd.push('-t', String(args.title).trim());
-                    if (args.body)
-                        editCmd.push('-b', String(args.body).trim());
-                    const res = await executor.run(editCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    editCmd.push(...body.argv);
+                    const res = await executor.run(editCmd, { ...runOpts, rawText: true, timeoutMs: 60_000, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return {
@@ -171,15 +186,16 @@ export function createDiscussionTool(executor) {
                     if (!args.discussion_number || typeof args.discussion_number !== 'number') {
                         throw new Error('comment 操作必须提供 discussion_number（讨论数字编号）');
                     }
-                    if (!args.body || typeof args.body !== 'string' || !args.body.trim()) {
-                        throw new Error('comment 操作必须提供 body（评论正文）');
+                    const body = resolveBodySource({ inline: trimInline(args.body), file: args.body_file }, { cwd, flag: '-b' });
+                    if (body.chars === 0) {
+                        throw new Error('comment 操作必须提供 body 或 body_file（评论正文）');
                     }
                     const commentCmd = [
                         'discussion', 'comment', String(args.discussion_number),
-                        '-b', args.body.trim(),
+                        ...body.argv,
                         ...repoArgs,
                     ];
-                    const res = await executor.run(commentCmd, { ...runOpts, rawText: true, timeoutMs: 60_000 });
+                    const res = await executor.run(commentCmd, { ...runOpts, rawText: true, timeoutMs: 60_000, ...stdinPatch(body) });
                     if (!res.ok)
                         throw new Error(res.error);
                     return {