dsh-github-flow 0.6.0 → 0.7.1

package/lib/executor.js

@@ -12,8 +12,10 @@ import { extractImageUrls } from './tools/image-utils.js';
 // 子模块纯函数解耦导入并对外部 Re-export 保证 100% 向后兼容
 import { parseGhVersion, compareGhVersions } from './executor/version-utils.js';
 import { spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput } from './executor/process-utils.js';
+import { buildPrReviewPayload, foldCommentsIntoBody, isLineCommentRejected } from './executor/pr-review.js';
 import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff, } from './executor/git-parser.js';
 import { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
+import { buildPlainFailureExcerpt, interpretRunLogError } from './executor/run-log.js';
 import { classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError } from './executor/error-classifier.js';
 export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff, getPlatformInstallGuide, getGhUpgradeHint, classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError, };
 const execFileAsync = promisify(execFile);
@@ -49,6 +51,35 @@ const ISSUE_DETAIL_FULL_FIELDS = 'number,title,state,stateReason,author,createdA
  * 正文与评论时间线——缺失的里程碑/关联 PR 只是少几个装饰位，不致命。
  */
 const ISSUE_DETAIL_BASE_FIELDS = 'number,title,state,author,createdAt,updatedAt,url,body,labels,assignees,milestone,comments';
+/**
+ * `gh run view --json` 的完整字段集（gh 2.96.0 实测合法全集）。
+ *
+ * `jobs` 的值是一个树：job{ databaseId,name,status,conclusion,startedAt,
+ * completedAt,url,steps[] }，step{ number,name,status,conclusion,startedAt,
+ * completedAt }。**step 没有 url**，所以 UI 只能给到 job 级外链。
+ * `attempt` 供「第 N 次重跑」显示；`displayTitle` 在 workflow 名称之外给出
+ * 这次运行的业务描述（PR 标题/提交信息）。
+ */
+const RUN_DETAIL_FULL_FIELDS = 'attempt,conclusion,createdAt,databaseId,displayTitle,event,headBranch,headSha,jobs,name,number,startedAt,status,updatedAt,url,workflowDatabaseId,workflowName';
+/**
+ * Run 详情的降级字段集（老 gh 遇未知字段会整体失败，与 issue 详情同一处置）。
+ *
+ * 只保留 jobs 这一棵不可替代的树 + 少量基础元数据：缺了 attempt/displayTitle
+ * 只是少两个装饰位，缺了 jobs 这个功能就不存在了。
+ */
+const RUN_DETAIL_BASE_FIELDS = 'databaseId,name,status,conclusion,jobs,url,createdAt';
+/** 单次按需拉日志的 job 上限：矩阵构建下几十个失败 job 不再是「一次点击」能承受的量 */
+const RUN_LOG_MAX_JOBS = 3;
+/** 日志摘要的字符预算：不进程模型上下文，只进浏览器 DOM，但仍要防几万字拖卡渲染 */
+const RUN_LOG_BUDGET_CHARS = 120_000;
+/**
+ * 单次日志请求的总时间预算（毫秒）。
+ *
+ * 为什么不是「每个 job 60s，有 3 个就 180s」：这条链路挂在 HTTP 路由上，宿主
+ * WebServer 是整个 GUI 共享的。一次点击把连接占住三分钟，等于把面板卡死。
+ * 超预算的 job 会进 errors[]（可单独重试），用户能在 90s 内拿到已拉到的部分。
+ */
+const RUN_LOG_TOTAL_BUDGET_MS = 90_000;
 /**
  * 把 `gh repo view --json` 的原始结果映射为 RepoMetadata。
  *
@@ -96,6 +127,14 @@ export class GhExecutor {
     maxOutputChars;
     /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
     maxOutputBytes;
+    /**
+     * 累计 gh 子进程调用次数（只增不清零，`run()` 每次 +1）。
+     *
+     * 为什么需要：任务原语（github_task）要如实汇报 `cost.ghCalls`，
+     * 而「原语是否真的比手动串步骤省钱」是这个能力存在的唯一判据。
+     * 消费方用「调用前快照 → 调用后求差」的方式取区间计数。
+     */
+    ghCalls = 0;
     /**
      * 列表类查询的默认条数上限。
      * 为什么挂在 executor 而不是给每个工具工厂加 config 参数：executor 是全部
@@ -180,11 +219,63 @@ export class GhExecutor {
             return recent;
         return explicitCwd || process.cwd();
     }
+    /**
+     * 18 个工具的唯一工作区入口：把 execContext 归一成 `{ cwd, sessionId }`。
+     *
+     * 为什么必须走这里而不是各工具写 `execContext?.cwd || process.cwd()`：
+     * 三级解析里第 1 级是「显式 cwd 且磁盘存在即原样返回」，而 `process.cwd()`
+     * 恒满足该条件——于是第 2 级「按 sessionId 反查真实工作区」**永远不会触发**。
+     * 工具层把 `process.cwd()` 当兜底传下去，等于把整个会话亲和机制架空。
+     *
+     * ⚠️ 刻意**不复用** `resolveWorkspaceCwd` 的第 3 级（`findMostRecentWorkspacePath`）：
+     * 那一级是给「完全无上下文的 CLI 场景」用的，会把目录定到**最近活跃的任意仓库**。
+     * 工具调用的默认目录必须可预测——落到一个与本会话无关的仓库意味着读错库、
+     * 更糟的是写到错库（merge / release create / label delete 都会打错地方）。
+     * 实测：抹掉 DSH_SESSION_ID 后 `resolveWorkspaceCwd(undefined, undefined)` 返回的是
+     * 一个与本会话无关的仓库路径，而 `process.cwd()` 是当前进程目录。
+     *
+     * 解析顺序：显式 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 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: 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: candidates[0] };
+    }
     /**
      * 安全执行 gh 命令
      * 采用 execFile 参数数组隔离，彻底杜绝 Shell 字符串拼接注入漏洞
      */
     async run(args, options = {}) {
+        /*
+         * gh 子进程调用计数（只增不清零）。
+         *
+         * 为什么放在 executor 而不是各工具里手数：任务原语（github_task）必须能如实
+         * 汇报 `cost.ghCalls`，而「原语是否真的省钱」是它存在的唯一判据。
+         * 手写计数必然与实际调用漂移——真实调用点只有这里一个。
+         */
+        this.ghCalls++;
         const cwd = this.resolveWorkspaceCwd(options.cwd, options.sessionId);
         const timeout = options.timeoutMs || this.defaultTimeoutMs;
         // 二进制模式（如 gh api 下载图片字节流）：stdout 保持 Buffer，绕过 UTF-8
@@ -248,7 +339,15 @@ export class GhExecutor {
             if (!rawOutput && errText) {
                 rawOutput = errText.trim();
             }
-            const outcome = truncateOutput(rawOutput, options.maxOutputChars ?? this.maxOutputChars, options.maxOutputBytes ?? this.maxOutputBytes);
+            const maxChars = options.maxOutputChars ?? this.maxOutputChars;
+            // 字节上限联动推导：若调用方显式放宽了字符上限（如放宽到 1MB），未指定 maxOutputBytes 时
+            // 必须按 4 倍自动放宽，绝不能死板回落到全局实例的 96KB（否则 >96KB 的输出会被静默判定截断）。
+            // 取 Math.max 是为了不压低用户在 Config 里配置的更大 maxOutputBytes。
+            const maxBytes = options.maxOutputBytes ??
+                (options.maxOutputChars
+                    ? Math.max(options.maxOutputChars * 4, this.maxOutputBytes)
+                    : this.maxOutputBytes);
+            const outcome = truncateOutput(rawOutput, maxChars, maxBytes);
             rawOutput = outcome.text;
             const truncated = outcome.truncated;
             // 如果未被截断且命令带有 --json 或包含 api，尝试解析为 JSON
@@ -425,18 +524,20 @@ export class GhExecutor {
      * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
      * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
      */
-    async getLocalGitStatus(cwd) {
+    async getLocalGitStatus(cwd, timeoutMs = 3_000) {
         try {
-            // 纯本地毫秒级；3s 超时兜底异常文件系统
+            // 默认 3s：概览面板只是"读不到就不渲染这一行"的兜底语义。
+            // 但安全闸门（ensureCleanWorkspace）必须显式传更长超时——大型仓库 / 网络盘上
+            // `git status` 冷启动超 3s 很常见，用 3s 会把"读不到"误判成"有风险"。
             const { stdout } = await execFileAsync('git', ['status', '-sb', '--porcelain'], {
                 cwd: cwd || undefined,
-                timeout: 3_000,
+                timeout: timeoutMs,
                 windowsHide: true,
             });
             return parseGitStatusOutput(String(stdout), 2000);
         }
         catch {
-            // 非 Git 目录 / git 未安装 / 超时：静默降级为 null（调用方不渲染该行）
+            // 非 Git 目录 / git 未安装 / 超时：静默降级为 null（调用方自行决定语义）
             return null;
         }
     }
@@ -486,7 +587,9 @@ export class GhExecutor {
         }
         try {
             // 1. 先用 porcelain status 获取该文件的状态码
-            let fileStatus = 'M';
+            // 默认值必须为空：旧实现默认 'M'，导致工作区干净的文件被报成「已修改」
+            // （UI 表现为"文件被改了，但 diff 是空的"）。状态只从 porcelain 结果推导。
+            let fileStatus = '';
             try {
                 const { stdout: statusOut } = await execFileAsync('git', ['status', '--porcelain', '--', cleanRel], {
                     cwd: targetCwd || undefined,
@@ -582,7 +685,7 @@ export class GhExecutor {
                 return {
                     ok: true,
                     filePath: cleanRel,
-                    status: fileStatus,
+                    status: fileStatus || 'M',
                     isBinary: true,
                     diff: 'Binary files differ',
                     additions: 0,
@@ -599,7 +702,8 @@ export class GhExecutor {
             return {
                 ok: true,
                 filePath: cleanRel,
-                status: fileStatus,
+                // porcelain 没给状态且没有 diff → 该文件其实是干净的，显式标 'clean' 而不是伪造成 'M'
+                status: fileStatus || (finalDiff ? 'M' : 'clean'),
                 diff: finalDiff || '没有检测到文本差异',
                 additions: diffStats.additions,
                 deletions: diffStats.deletions,
@@ -718,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、最新提交简述与相对时间。
@@ -741,12 +909,141 @@ export class GhExecutor {
             return null;
         }
     }
+    /**
+     * 发版输入：最近 tag + 该 tag 以来的提交（供 `github_task(prepare_release)` 使用）。
+     *
+     * 为什么要在 executor 里开这个口子，而不是让工具自己拼 git 命令：
+     * 命令形态必须集中（本文件顶部就是"git 白名单"纪律），否则每个新工具都会
+     * 自己发明一套 argv，`phase34` 的契约网也就管不到它们了。
+     *
+     * 安全性：两条命令的形态**全部固定**——`describe --tags --abbrev=0` 无参数注入；
+     * log 的修订范围段只拼 `git describe` 自己的输出，且先过 `/^[A-Za-z0-9._\/-]+$/`
+     * 白名单校验，杜绝把任意字符串当 revision 传进 git。
+     */
+    async getReleaseInputs(cwd, fromTagOverride) {
+        const empty = {
+            ok: false,
+            fromTag: null,
+            commits: [],
+            totalCommits: 0,
+        };
+        const runOpts = { cwd: cwd || undefined, timeout: 5_000, windowsHide: true };
+        let fromTag = null;
+        /*
+         * 显式指定的起始 tag 优先，且**必须真的作为 range 起点**。
+         *
+         * 为什么强调：只拿它当「版本号基数」而不改 range，会出现「按 v1.0.0 算版本、
+         * 但统计的是 v1.2.0 以来的提交」——数字与标签对不上，比直接报错更坏。
+         */
+        const override = typeof fromTagOverride === 'string' ? fromTagOverride.trim() : '';
+        if (override) {
+            /*
+             * 两条校验缺一不可：
+             * - 字符白名单挡住 `;` `$()` 这类命令注入；
+             * - **禁止以 `-` 开头**：它会被拼进 `git log <tag>..HEAD` 的第一个位置，
+             *   git 会把 `-p..HEAD` 当成未知选项（实测报错）。虽然成不了真正的注入，
+             *   但「用户输入永远不许以 - 开头」是这条通道的基本纪律。
+             */
+            if (override.startsWith('-') || !/^[A-Za-z0-9._/-]+$/.test(override)) {
+                return { ...empty, error: `非法的 from_tag：${override}（只允许字母/数字/./_/-/，且不能以 - 开头）` };
+            }
+            fromTag = override;
+        }
+        else {
+            try {
+                const tagRes = await execFileAsync('git', ['describe', '--tags', '--abbrev=0'], runOpts);
+                const raw = String(tagRes.stdout || '').trim();
+                // 白名单：describe 的输出来自仓库自身，但仍要挡住 `..`、空白与 shell 元字符
+                if (raw && /^[A-Za-z0-9._/-]+$/.test(raw))
+                    fromTag = raw;
+            }
+            catch {
+                // 没有任何 tag 是正常状态（新仓库），不是错误
+                fromTag = null;
+            }
+        }
+        try {
+            const range = fromTag ? `${fromTag}..HEAD` : 'HEAD';
+            const logRes = await execFileAsync('git', 
+            // %b 带出提交正文：BREAKING CHANGE 常常只写在正文里，只看标题会漏判 major
+            ['log', range, '-n', '300', '--pretty=format:%x1e%h%x1f%s%x1f%an%x1f%ad%x1f%b'], runOpts);
+            const text = String(logRes.stdout || '');
+            const commits = text
+                .split('\x1e')
+                .map((chunk) => chunk.trim())
+                .filter(Boolean)
+                .map((chunk) => {
+                const parts = chunk.split('\x1f');
+                return {
+                    sha: String(parts[0] || ''),
+                    subject: String(parts[1] || ''),
+                    author: String(parts[2] || ''),
+                    date: String(parts[3] || ''),
+                    // 正文只取前 500 字符：够判 BREAKING CHANGE，又不至于把整包撑大
+                    body: String(parts.slice(4).join('\x1f') || '').slice(0, 500),
+                };
+            });
+            return { ok: true, fromTag, commits, totalCommits: commits.length };
+        }
+        catch (err) {
+            return { ...empty, fromTag, error: err?.message || '读取提交记录失败' };
+        }
+    }
+    /**
+     * 工作区干净度闸门（唯一实现）。
+     *
+     * 为什么抽成公共方法：会改变工作区分支/内容的入口有三条——界面切分支（switchGitBranch）、
+     * `github_pr(checkout)`、`github_issue(develop)`。此前只有第一条有脏检查，后两条直穿，
+     * 于是「强阻断」的成文承诺只对界面成立。安全不变量必须只有一处实现。
+     *
+     * 三态语义（fail-closed）：
+     * - `null`（git 读不到）→ 拒绝。读不到状态≠干净，放行等于闸门失效。
+     * - `dirtyCount > 0` → 拒绝，并带前 5 条样例便于用户判断。
+     * - 其余 → 放行。
+     *
+     * 超时为什么单独给 20s：`getLocalGitStatus` 默认 3s 是给概览面板用的（读不到就不渲染那一行），
+     * 但这里是一次安全判决——大型仓库 / 网络盘 / OneDrive 同步目录下 `git status` 冷启动超 3s
+     * 很常见，用 3s 会把"慢"误判成"脏/不可用"，直接把 checkout 挡死。
+     */
+    async ensureCleanWorkspace(cwd) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        // 先区分"根本不是 Git 仓库"与"是仓库但读不到状态"——两者对用户的可操作性完全不同。
+        if (!hasGitDir(targetCwd)) {
+            return {
+                ok: false,
+                reason: 'unknown',
+                dirtyCount: 0,
+                samples: [],
+                error: `当前目录不是 Git 仓库（${targetCwd}），无法执行需要切换分支的操作。`,
+            };
+        }
+        const gitSt = await this.getLocalGitStatus(targetCwd, 20_000);
+        if (gitSt === null) {
+            return {
+                ok: false,
+                reason: 'unknown',
+                dirtyCount: 0,
+                samples: [],
+                error: '读取工作区 Git 状态失败（git 不可用、超时或权限不足）。为避免覆盖本地改动，已拒绝执行。',
+            };
+        }
+        if (gitSt.dirtyCount > 0) {
+            return {
+                ok: false,
+                reason: 'dirty',
+                dirtyCount: gitSt.dirtyCount,
+                samples: (gitSt.dirtyFiles || []).slice(0, 5).map((f) => `${f.status} ${f.path}`),
+                error: `工作区有 ${gitSt.dirtyCount} 个未提交的文件变更。为防止代码被覆盖，请先提交或保存后再执行。`,
+            };
+        }
+        return { ok: true, dirtyCount: 0, samples: [] };
+    }
     /**
      * 安全切换当前工作区的 Git 分支。
      * 三重安全防御纪律：
      * 1. 目标工作区必须存在有效的 .git 目录；
      * 2. 分支名称严格执行字符白名单校验，防命令行参数注入；
-     * 3. 检查工作区干净度（dirtyCount），若有未提交或未保存的变更直接阻断，杜绝代码被破坏性覆盖。
+     * 3. 工作区干净度交给 ensureCleanWorkspace（唯一实现，与 checkout / develop 共用）。
      */
     async switchGitBranch(cwd, branchName) {
         const targetCwd = this.resolveWorkspaceCwd(cwd);
@@ -759,12 +1056,9 @@ export class GhExecutor {
             return { ok: false, error: '非法分支名称，仅允许字母、数字、短横线、下划线与斜杠组合' };
         }
         // 防线二：工作区未提交变更阻断（Dirty File Guard）
-        const gitSt = await this.getLocalGitStatus(targetCwd);
-        if (gitSt && gitSt.dirtyCount > 0) {
-            return {
-                ok: false,
-                error: `工作区有 ${gitSt.dirtyCount} 个未提交的文件变更。为防止代码被覆盖，请先提交或保存后再切换分支。`,
-            };
+        const guard = await this.ensureCleanWorkspace(targetCwd);
+        if (!guard.ok) {
+            return { ok: false, error: guard.error };
         }
         try {
             let args = ['checkout', cleanBranch];
@@ -890,8 +1184,8 @@ export class GhExecutor {
         if (!num || isNaN(num) || num <= 0) {
             return { ok: false, error: '缺少有效 PR 编号（必须为正整数）' };
         }
-        const cleanRepo = typeof repo === 'string' ? repo.trim() : '';
-        if (cleanRepo && !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(cleanRepo)) {
+        const cleanRepo = this.normalizeRepoFullName(repo);
+        if (cleanRepo === null) {
             return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
         }
         const viewArgs = [
@@ -899,7 +1193,10 @@ export class GhExecutor {
             'view',
             String(num),
             '--json',
-            'number,title,state,isDraft,url,createdAt,updatedAt,author,baseRefName,headRefName,body,reviewDecision,statusCheckRollup,comments,reviews,files,additions,deletions',
+            // headRefOid/baseRefOid：分支会移动，SHA 才是可钉住的审查锚点（s7 §2.1）
+            // changedFiles：`--json files` 在 100 条处静默截断，只有这个数字能判定「清单被截了」
+            // headRepositoryOwner：`prDetail.headRepoOwner` 的取值来源（此前恒 undefined）
+            'number,title,state,isDraft,url,createdAt,updatedAt,author,baseRefName,headRefName,headRefOid,baseRefOid,changedFiles,headRepositoryOwner,body,reviewDecision,statusCheckRollup,comments,reviews,files,additions,deletions',
         ];
         if (cleanRepo)
             viewArgs.push('-R', cleanRepo);
@@ -963,6 +1260,24 @@ export class GhExecutor {
         }
         const fullDiff = rDiff.ok ? (typeof rDiff.data === 'string' ? rDiff.data : rDiff.rawOutput || '') : '';
         const fileDiffs = splitUnifiedDiff(fullDiff);
+        const files = Array.isArray(raw.files)
+            ? raw.files.map((f) => ({
+                path: String(f.path || ''),
+                additions: Number(f.additions) || 0,
+                deletions: Number(f.deletions) || 0,
+                changeType: String(f.changeType || 'MODIFIED'),
+            }))
+            : [];
+        /*
+         * 三个截断字段各自回答一个不同问题，缺一不可（s7 §2.5）：
+         * - changedFiles   ：仓库里这个 PR 到底改了多少个文件（权威总数）
+         * - filesTruncated ：清单被 gh 的 100 条上限裁掉了吗（cli/cli#12522 静默截断）
+         * - diffIncomplete ：清单里有、但切片里没有对应 diff 的文件（数据缺失，不是「没改动」）
+         * 把三者混成一个布尔值，界面就只能说「可能不全」，用户无法判断该去做什么。
+         */
+        const changedFiles = Number(raw.changedFiles) || files.length;
+        const filesTruncated = files.length < changedFiles;
+        const diffIncomplete = files.some((f) => !fileDiffs[f.path]);
         const prDetail = {
             number: Number(raw.number) || num,
             title: String(raw.title || ''),
@@ -977,20 +1292,18 @@ export class GhExecutor {
             },
             headRefName: String(raw.headRefName || ''),
             baseRefName: String(raw.baseRefName || ''),
+            headRefOid: raw.headRefOid ? String(raw.headRefOid) : undefined,
+            baseRefOid: raw.baseRefOid ? String(raw.baseRefOid) : undefined,
             headRepoOwner: raw.headRepositoryOwner?.login ? String(raw.headRepositoryOwner.login) : undefined,
             body: String(raw.body || ''),
             reviewDecision: raw.reviewDecision ? String(raw.reviewDecision) : undefined,
             statusCheckRollup: raw.statusCheckRollup,
             additions: Number(raw.additions) || 0,
             deletions: Number(raw.deletions) || 0,
-            files: Array.isArray(raw.files)
-                ? raw.files.map((f) => ({
-                    path: String(f.path || ''),
-                    additions: Number(f.additions) || 0,
-                    deletions: Number(f.deletions) || 0,
-                    changeType: String(f.changeType || 'MODIFIED'),
-                }))
-                : [],
+            files,
+            changedFiles,
+            ...(filesTruncated ? { filesTruncated: true } : {}),
+            ...(diffIncomplete ? { diffIncomplete: true } : {}),
             comments: Array.isArray(raw.comments)
                 ? raw.comments.map((c) => ({
                     id: String(c.id || ''),
@@ -1019,6 +1332,92 @@ export class GhExecutor {
         };
         return { ok: true, data: prDetail };
     }
+    /**
+     * 提交带行级评注的 PR review（REST 通道）。
+     *
+     * 为什么必须走 REST：`gh pr review` 只有 `--approve/--request-changes/--comment`，
+     * 没有任何行级参数（`gh pr review --help` 里 line/side/path 零命中）。行级评注
+     * 的唯一入口是 `POST /repos/{owner}/{repo}/pulls/{n}/reviews` 的 `comments[]`。
+     *
+     * 为什么一次 review 一个请求（而不是逐条 `POST /pulls/{n}/comments`）：
+     * 通知只发一轮，也避开 secondary rate limit 的「创建内容过快」判定。
+     *
+     * 422 降级：行级评注被拒（典型原因：该行不在 diff 的可评论侧，如纯删除行）
+     * 时，把评注折叠进 review 正文重试一次。内容不能丢，但降级必须显式可见。
+     */
+    async createPrReview(cwd, repo, prNumber, input) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        const num = Number(prNumber);
+        if (!num || isNaN(num) || num <= 0) {
+            return { ok: false, error: '缺少有效 PR 编号（必须为正整数）' };
+        }
+        // 仓库名优先用显式参数；缺省时从本地 git remote 推导（与 getPrDetail 同一套规则）
+        const cleanRepo = this.normalizeRepoFullName(repo);
+        if (cleanRepo === null) {
+            return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
+        }
+        const fullName = cleanRepo || this.getRepoIdentityFromLocal(targetCwd)?.nameWithOwner || '';
+        if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(fullName)) {
+            return { ok: false, error: '无法确定仓库全名：请传 repo 参数，或在 Git 仓库目录下调用' };
+        }
+        const built = buildPrReviewPayload(input);
+        if (!built.ok || !built.payload) {
+            return { ok: false, error: `评注参数校验未通过：\n- ${(built.errors || ['未知错误']).join('\n- ')}` };
+        }
+        const payload = built.payload;
+        const endpoint = `repos/${fullName}/pulls/${num}/reviews`;
+        const post = (body) => this.run(['api', '--method', 'POST', endpoint, '--input', '-'], {
+            cwd: targetCwd,
+            timeoutMs: 20_000,
+            stdin: JSON.stringify(body),
+        });
+        const first = await post(payload);
+        if (first.ok) {
+            const data = first.data;
+            return {
+                ok: true,
+                data: {
+                    id: data?.id,
+                    htmlUrl: data?.html_url,
+                    state: data?.state,
+                    submittedAt: data?.submitted_at,
+                    // 逐条回传评论地址，供人复核「到底挂到了哪一行」
+                    comments: Array.isArray(data?.comments)
+                        ? data.comments.map((c) => ({
+                            path: String(c?.path || ''),
+                            line: typeof c?.line === 'number' ? c.line : undefined,
+                            htmlUrl: c?.html_url ? String(c.html_url) : undefined,
+                        }))
+                        : [],
+                },
+            };
+        }
+        // 只在「行级评注被拒」时降级；403/404/网络错误原样抛出（降级也没用）
+        const hasComments = Array.isArray(payload.comments) && payload.comments.length > 0;
+        if (hasComments && isLineCommentRejected(first.error || '')) {
+            const folded = foldCommentsIntoBody(payload.comments, payload.body);
+            const retry = await post({ ...payload, body: folded, comments: undefined });
+            // 把 GitHub 的原始拒绝原因带进说明里：否则用户只看到「已折叠进正文」，
+            // 却不知道是「行不在 diff 可评论侧」还是「path 根本不存在」——两者处置完全不同。
+            const why = String(first.error || '').replace(/\s+/g, ' ').trim().slice(0, 200);
+            if (retry.ok) {
+                const data = retry.data;
+                return {
+                    ok: true,
+                    degraded: true,
+                    degradedReason: `行级评注被 GitHub 拒绝（${why}），已折叠进 review 正文提交，内容未丢失。`,
+                    data: { id: data?.id, htmlUrl: data?.html_url, state: data?.state, submittedAt: data?.submitted_at, comments: [] },
+                };
+            }
+            return {
+                ok: false,
+                degraded: true,
+                degradedReason: `行级评注被拒（${why}）后降级重试仍失败。`,
+                error: retry.error || first.error,
+            };
+        }
+        return { ok: false, error: first.error };
+    }
     /**
      * 获取 Issue 完整详情（供 IssueDetailModal 在线查看消费）。
      *
@@ -1035,8 +1434,8 @@ export class GhExecutor {
         if (!num || isNaN(num) || num <= 0 || !Number.isInteger(num)) {
             return { ok: false, error: '缺少有效 Issue 编号（必须为正整数）' };
         }
-        const cleanRepo = typeof repo === 'string' ? repo.trim() : '';
-        if (cleanRepo && !/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(cleanRepo)) {
+        const cleanRepo = this.normalizeRepoFullName(repo);
+        if (cleanRepo === null) {
             return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
         }
         const buildArgs = (fields) => {
@@ -1166,6 +1565,249 @@ export class GhExecutor {
         };
         return { ok: true, data: detail };
     }
+    /**
+     * 详情类接口的仓库参数归一化（PR / Issue / Run 共用）。
+     *
+     * 返回 `''` = 未传（由本地 remote 决定）；返回 `null` = 非法。
+     *
+     * 为什么要收编三处各自的校验：历史实现各写一份正则，只有 `setDefaultRepo` 额外
+     * 拒绝 `-` 开头与 `..`，其余靠「恒以 `-R <value>` 成对传入」兜底（复核报告 C-13）。
+     * 「成对传入所以安全」是当前调用形状的安全，不是接口的安全——多一处调用方就多
+     * 一次赌。统一到这里后，`-` 开头/`..`/反斜杠在任何详情入口都进不来。
+     */
+    normalizeRepoFullName(repo) {
+        const clean = typeof repo === 'string' ? repo.trim() : '';
+        if (!clean)
+            return '';
+        if (clean.startsWith('-') || clean.includes('..') || clean.includes('\\'))
+            return null;
+        if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(clean))
+            return null;
+        return clean;
+    }
+    /**
+     * 获取单次 Actions Run 的完整详情（run + jobs + steps）。
+     *
+     * 架构设计：
+     * 1. **run_id 只认纯数字**。它会被当作 `gh run view` 的位置参数拼进 argv，
+     *    不做白名单就等于把「用参数值注入 flag」这条已知缺陷（复核报告 C-01）
+     *    复制到新通道——`--web`、`--log` 都能冒充编号。
+     * 2. 单次往返拿全：`jobs` 里已经包含 steps 树，没有需要并行拉取的第二路。
+     * 3. **日志不在这里拉**。实测单次失败日志 4–40 秒（本机代理下还直接连接重置），
+     *    挂在详情上等于让弹窗首屏去赌网络；日志走 getRunLogExcerpts() 按需拉。
+     */
+    async getRunDetail(cwd, runId, repo) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        const id = String(runId ?? '').trim();
+        if (!/^\d+$/.test(id) || Number(id) <= 0) {
+            return { ok: false, error: '缺少有效 Run ID（必须为正整数）' };
+        }
+        const cleanRepo = this.normalizeRepoFullName(repo);
+        if (cleanRepo === null) {
+            return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
+        }
+        const buildArgs = (fields) => {
+            const args = ['run', 'view', id, '--json', fields];
+            if (cleanRepo)
+                args.push('-R', cleanRepo);
+            return args;
+        };
+        /**
+         * 输出阈值必须显式放宽。
+         *
+         * 为什么：矩阵构建的 jobs 数组动辄上百个 job、每个十几步，JSON 轻松过 100KB；
+         * 沿用默认 24KB 会跳过 JSON.parse，data 恒为 undefined，于是弹窗渲染出
+         * 「元数据全空 + 零 job」的假详情——比报错更糟（同 getIssueDetail 的教训）。
+         */
+        const execOpts = {
+            cwd: targetCwd,
+            timeoutMs: 20_000,
+            maxOutputChars: 2_000_000,
+            maxOutputBytes: 8 * 1024 * 1024,
+        };
+        let fieldsDegraded = false;
+        let r = await this.run(buildArgs(RUN_DETAIL_FULL_FIELDS), execOpts);
+        if (!r.ok && /Unknown JSON field/i.test(String(r.error || ''))) {
+            fieldsDegraded = true;
+            r = await this.run(buildArgs(RUN_DETAIL_BASE_FIELDS), execOpts);
+        }
+        if (!r.ok) {
+            return { ok: false, error: r.error || `获取 Run #${id} 详情失败` };
+        }
+        // 截断 / 解析失败必须显式失败：渲染空 jobs 会被读成「这次运行没有 job」
+        if (r.truncated || !r.data || typeof r.data !== 'object') {
+            const link = cleanRepo ? `https://github.com/${cleanRepo}/actions/runs/${id}` : '仓库的 Actions 页面';
+            return {
+                ok: false,
+                error: `Run #${id} 的 job 清单过长，已超出插件单次读取上限。请在浏览器中查看完整运行（${link}）。`,
+            };
+        }
+        const raw = r.data;
+        const jobs = Array.isArray(raw.jobs)
+            ? raw.jobs
+                .filter((j) => j && (j.databaseId || j.name))
+                .map((j) => {
+                const steps = Array.isArray(j.steps)
+                    ? j.steps
+                        .filter((s) => s && typeof s === 'object')
+                        .map((s) => ({
+                        number: Number(s.number) || 0,
+                        name: String(s.name || ''),
+                        status: String(s.status || ''),
+                        ...(s.conclusion ? { conclusion: String(s.conclusion) } : {}),
+                        ...(s.startedAt ? { startedAt: String(s.startedAt) } : {}),
+                        ...(s.completedAt ? { completedAt: String(s.completedAt) } : {}),
+                    }))
+                    : [];
+                return {
+                    databaseId: Number(j.databaseId) || 0,
+                    name: String(j.name || '未命名 job'),
+                    status: String(j.status || ''),
+                    ...(j.conclusion ? { conclusion: String(j.conclusion) } : {}),
+                    ...(j.startedAt ? { startedAt: String(j.startedAt) } : {}),
+                    ...(j.completedAt ? { completedAt: String(j.completedAt) } : {}),
+                    ...(j.url ? { url: String(j.url) } : {}),
+                    steps,
+                };
+            })
+            : [];
+        // 失败口径只算一次，UI 直接消费（避免前端再推导出第二套口径）
+        const failedJobs = jobs.filter((j) => j.conclusion === 'failure').length;
+        const failedSteps = jobs.reduce((sum, j) => sum + j.steps.filter((s) => s.conclusion === 'failure').length, 0);
+        const detail = {
+            runId: Number(raw.databaseId) || Number(id),
+            ...(typeof raw.attempt === 'number' && raw.attempt > 0 ? { attempt: raw.attempt } : {}),
+            name: String(raw.name || raw.workflowName || `Run ${id}`),
+            ...(raw.displayTitle ? { displayTitle: String(raw.displayTitle) } : {}),
+            status: String(raw.status || ''),
+            ...(raw.conclusion ? { conclusion: String(raw.conclusion) } : {}),
+            ...(raw.event ? { event: String(raw.event) } : {}),
+            ...(raw.headBranch ? { headBranch: String(raw.headBranch) } : {}),
+            ...(raw.headSha ? { headSha: String(raw.headSha) } : {}),
+            url: String(raw.url || ''),
+            createdAt: String(raw.createdAt || ''),
+            ...(raw.startedAt ? { startedAt: String(raw.startedAt) } : {}),
+            updatedAt: String(raw.updatedAt || ''),
+            ...(raw.workflowName ? { workflowName: String(raw.workflowName) } : {}),
+            jobs,
+            failedJobs,
+            failedSteps,
+            ...(fieldsDegraded ? { fieldsDegraded: true } : {}),
+        };
+        return { ok: true, data: detail };
+    }
+    /**
+     * 按需拉取失败日志并压成纯文本摘要（供 Run 详情弹窗消费）。
+     *
+     * 与 github_run(log_failed) 的关系：同一份 `--log-failed` 原始输出、同一套锚点
+     * 萃取与尾部回退，只是排版不同（弹窗要的是 `<pre>` 纯文本，不是 Markdown）。
+     *
+     * 为什么逐 job 拉而不是整 run 一次拉：`gh run view --log-failed` 会把**整次运行**
+     * 的日志包都下载下来再过滤，矩阵构建下等于为了一个失败 job 拖几十 MB；`-j <jobId>`
+     * 是 gh 支持的定向形态（见 `gh run view --help`），失败 job 通常只有 1–3 个。
+     *
+     * 为什么单个 job 失败仍返回 ok:true：部分成功比整体失败有用——已拿到的块照常展示，
+     * 失败的那个进 errors[] 并在界面上显式可重试。只有参数非法才是 ok:false。
+     */
+    async getRunLogExcerpts(cwd, runId, jobIds, repo, 
+    /**
+     * 本批日志的总预算（毫秒，默认 `RUN_LOG_TOTAL_BUDGET_MS`）。
+     *
+     * 为什么需要：单 job 超时 60s × 最多 3 个串行 = 最坏 180s。这个调用挂在 HTTP
+     * 路由上，而宿主 WebServer 是全 GUI 共享的——一次点击占住三分钟不可接受。
+     * 超预算的 job 进 `errors[]`（显式、可单独重试），而不是让连接一直挂着。
+     * 允许外部传入只为可测：传 0 能验证「超预算」分支而不必真的等待。
+     */
+    opts = {}) {
+        const targetCwd = this.resolveWorkspaceCwd(cwd);
+        const id = String(runId ?? '').trim();
+        if (!/^\d+$/.test(id) || Number(id) <= 0) {
+            return { ok: false, error: '缺少有效 Run ID（必须为正整数）' };
+        }
+        const cleanRepo = this.normalizeRepoFullName(repo);
+        if (cleanRepo === null) {
+            return { ok: false, error: '非法仓库全名参数（仅允许 owner/repo 格式）' };
+        }
+        const wanted = Array.from(new Set((Array.isArray(jobIds) ? jobIds : [])
+            .map((v) => String(v ?? '').trim())
+            .filter((v) => /^\d+$/.test(v) && Number(v) > 0)));
+        if (wanted.length === 0) {
+            return { ok: false, error: '缺少有效 job_id（必须为正整数，最多 3 个）' };
+        }
+        // 超上限必须显式拒绝：静默 slice 会让调用方以为 5 个 job 的日志都拉了，
+        // 与仓库自己立的「截断必须可见」纪律（filesTruncated / totalUnknown）相悖。
+        if (wanted.length > RUN_LOG_MAX_JOBS) {
+            return {
+                ok: false,
+                error: `一次最多拉取 ${RUN_LOG_MAX_JOBS} 个 job 的失败日志（本次请求 ${wanted.length} 个）。请分批重试，或直接在 GitHub 查看完整日志。`,
+            };
+        }
+        // 名字从详情树里取（job id → 名称）。取不到不影响拉日志，但**必须显式标注**：
+        // 名字退化成 `job #111` 是可见的降级，不能让它悄悄发生（本仓的降级纪律）。
+        const detail = await this.getRunDetail(targetCwd, id, cleanRepo || undefined).catch(() => null);
+        const nameById = new Map();
+        for (const job of detail && detail.ok && detail.data ? detail.data.jobs : []) {
+            if (job.databaseId > 0)
+                nameById.set(job.databaseId, job.name);
+        }
+        const namesUnavailable = wanted.some((jobId) => !nameById.has(Number(jobId)));
+        const jobs = [];
+        const errors = [];
+        // 总预算：3 个 job 各 60s 串行会把一条 HTTP 请求拖到 180s（见方法注释）
+        const budget = Number.isFinite(opts.totalBudgetMs)
+            ? Math.max(0, Math.floor(opts.totalBudgetMs))
+            : RUN_LOG_TOTAL_BUDGET_MS;
+        const deadline = Date.now() + budget;
+        // 串行而非并发：每次都是一次整包下载，并发只会同时挤爆代理与 gh 缓存目录
+        for (const jobId of wanted) {
+            const jobName = nameById.get(Number(jobId)) || `job #${jobId}`;
+            // 定向日志通道：`-j <jobId> --log-failed` 只下这个 job 的失败步骤日志
+            const logArgs = ['run', 'view', id, '-j', jobId, '--log-failed'];
+            if (cleanRepo)
+                logArgs.push('-R', cleanRepo);
+            // 预算在**每次**调用前重算：前一个 job 慢，后面的就该直接判超预算而不是再赌一次
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                errors.push({
+                    jobName,
+                    error: `超出本批日志总预算（${Math.round(budget / 1000)}s），该 job 未拉取。请单独重试。`,
+                });
+                continue;
+            }
+            const res = await this.run(logArgs, {
+                cwd: targetCwd,
+                // 单个 job 最多 60s，但绝不越过本批总预算
+                timeoutMs: Math.min(60_000, remaining),
+                rawText: true,
+                maxOutputChars: 2_000_000,
+                maxOutputBytes: 8 * 1024 * 1024,
+            });
+            if (!res.ok) {
+                const friendly = interpretRunLogError(String(res.error || ''), id);
+                if (friendly) {
+                    // 确定性结论（该 job 没有失败步骤 / 缓存目录无权限）不是故障，进正文而非 errors
+                    jobs.push({ jobId: Number(jobId), jobName, excerpt: friendly, truncated: false });
+                }
+                else {
+                    errors.push({ jobName, error: String(res.error || '日志拉取失败').trim().slice(0, 400) });
+                }
+                continue;
+            }
+            const built = buildPlainFailureExcerpt(res.rawOutput || '', {
+                budget: RUN_LOG_BUDGET_CHARS,
+                truncated: Boolean(res.truncated),
+            });
+            jobs.push({ jobId: Number(jobId), jobName, excerpt: built.text, truncated: built.truncated });
+        }
+        const data = {
+            runId: Number(id),
+            jobs,
+            ...(errors.length > 0 ? { errors } : {}),
+            ...(namesUnavailable ? { namesUnavailable: true } : {}),
+            fetchedAt: new Date().toISOString(),
+        };
+        return { ok: true, data };
+    }
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     getPlatformInstallGuide() {
         return getPlatformInstallGuide();