dsh-github-flow 0.6.0 → 0.7.1

package/lib/executor/pr-review.js

@@ -0,0 +1,175 @@
+/**
+ * PR 行级评注写入：payload 构造、校验与 422 降级（纯函数）。
+ *
+ * 为什么单独一个模块：
+ * 1. `gh pr review` 没有行级参数（`gh pr review --help` 里 line/side/path 零命中），
+ *    只能走 `POST /repos/{owner}/{repo}/pulls/{n}/reviews` 的 `comments[]`；
+ * 2. 「哪些错误可以在发请求前拦住」「422 怎么降级」是纯逻辑，必须能脱离网络单测；
+ * 3. executor 只负责发请求，校验与降级策略放在这里，避免 executor 继续膨胀。
+ *
+ * 严格按 REST 文档字段构造请求体，未自造任何键。
+ */
+import { normalizeSeverity } from '../review-rules.js';
+/** 单次 review 的行级评注上限。超过就拆多次，一次一个请求 = 通知只发一轮 */
+export const MAX_REVIEW_COMMENTS = 50;
+function toPositiveInt(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) && Number.isInteger(n) && n > 0 ? n : null;
+}
+/**
+ * 归一化单条评注。
+ *
+ * 归一化而非报错的项：`side` 非法 → 回落到 `RIGHT`（新代码侧是最常见意图，
+ * 且报错会让一次批量 review 因为一个拼写错误整体失败）。
+ * 必须报错的项：缺 `path` / 缺 `body` / `line` 给了但不是正整数——
+ * 这三类在 REST 侧必然 422，提前拦住比事后降级更诚实。
+ */
+function normalizeComment(raw, index) {
+    const errors = [];
+    const at = `comments[${index}]`;
+    const p = typeof raw?.path === 'string' ? raw.path.trim() : '';
+    if (!p)
+        errors.push(`${at}.path 必填（文件相对路径）`);
+    const body = typeof raw?.body === 'string' ? raw.body.trim() : '';
+    if (!body)
+        errors.push(`${at}.body 必填（评注正文不能为空）`);
+    let line;
+    if (raw?.line !== undefined && raw?.line !== null) {
+        const n = toPositiveInt(raw.line);
+        if (n === null)
+            errors.push(`${at}.line 必须是正整数（当前 ${JSON.stringify(raw.line)}）`);
+        else
+            line = n;
+    }
+    let startLine;
+    if (raw?.start_line !== undefined && raw?.start_line !== null) {
+        const n = toPositiveInt(raw.start_line);
+        if (n === null)
+            errors.push(`${at}.start_line 必须是正整数（当前 ${JSON.stringify(raw.start_line)}）`);
+        else
+            startLine = n;
+    }
+    if (line !== undefined && startLine !== undefined && startLine > line) {
+        errors.push(`${at}.start_line(${startLine}) 不能大于 line(${line})`);
+    }
+    const sideRaw = typeof raw?.side === 'string' ? raw.side.toUpperCase() : '';
+    const side = sideRaw === 'LEFT' ? 'LEFT' : 'RIGHT';
+    const startSideRaw = typeof raw?.start_side === 'string' ? raw.start_side.toUpperCase() : '';
+    const startSide = startLine === undefined ? undefined : startSideRaw === 'LEFT' ? 'LEFT' : 'RIGHT';
+    if (errors.length > 0)
+        return { ok: false, errors };
+    /*
+     * 没有 line → 文件级评论（`subject_type: 'file'`）。
+     *
+     * 为什么必须显式声明而不是留空：REST 的 `comments[]` 里 `line` 实际是必填的，
+     * 只给 `path` 会被判为「非法行级评论」直接 422。声明成 file 级之后，
+     * 「只想对某个文件留一句」成了合法输入，也不必再走一次注定失败的请求。
+     */
+    if (line === undefined) {
+        return { ok: true, value: { path: p, subject_type: 'file', body: normalizeSeverity(body) } };
+    }
+    return {
+        ok: true,
+        value: {
+            path: p,
+            line,
+            side,
+            ...(startLine !== undefined ? { start_line: startLine, start_side: startSide } : {}),
+            // 严重度前缀在此统一补齐：只补不删，[P0]/[P1] 原样保留
+            body: normalizeSeverity(body),
+        },
+    };
+}
+/**
+ * 构造 REST review 请求体。
+ *
+ * @param input.event    review 判定，缺省 COMMENT
+ * @param input.body     整体说明
+ * @param input.comments 行级评注（空数组等价于不传 → 调用方应走原 gh pr review 路径）
+ * @param input.commit_id 可选锚点 SHA
+ */
+export function buildPrReviewPayload(input) {
+    const errors = [];
+    const rawEvent = typeof input?.event === 'string' ? input.event.toUpperCase() : '';
+    const event = rawEvent === 'APPROVE' || rawEvent === 'REQUEST_CHANGES' || rawEvent === 'COMMENT' ? rawEvent : 'COMMENT';
+    if (rawEvent && rawEvent !== event) {
+        errors.push(`event 只能是 COMMENT / APPROVE / REQUEST_CHANGES（当前 ${JSON.stringify(input.event)}）`);
+    }
+    const list = Array.isArray(input?.comments) ? input.comments : [];
+    if (list.length > MAX_REVIEW_COMMENTS) {
+        errors.push(`单次最多 ${MAX_REVIEW_COMMENTS} 条行级评注（当前 ${list.length} 条），请拆分多次提交`);
+    }
+    const comments = [];
+    for (let i = 0; i < list.length; i++) {
+        const r = normalizeComment(list[i], i);
+        if (r.ok)
+            comments.push(r.value);
+        else
+            errors.push(...r.errors);
+    }
+    const summary = typeof input?.body === 'string' ? input.body.trim() : '';
+    /*
+     * 整体说明只在「提意见」时补严重度前缀，APPROVE 不补。
+     *
+     * 为什么：`[P2] LGTM` 是把优先级标签套在一句同意上，语义上说不通——严重度
+     * 是给**问题**定级的，不是给结论定级的。行级评注则一律补（每条都是一条意见）。
+     */
+    const bodyText = summary
+        ? event === 'APPROVE'
+            ? summary
+            : normalizeSeverity(summary)
+        : comments.length > 0
+            ? `[P2] 共 ${comments.length} 条行级评注`
+            : '';
+    if (!bodyText && event !== 'APPROVE') {
+        errors.push('body 必填：REQUEST_CHANGES / COMMENT 需要一段整体说明');
+    }
+    const commitId = typeof input?.commit_id === 'string' ? input.commit_id.trim() : '';
+    if (commitId && !/^[0-9a-f]{7,40}$/i.test(commitId)) {
+        errors.push(`commit_id 必须是 7–40 位十六进制 SHA（当前 ${JSON.stringify(input.commit_id)}）`);
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const payload = {
+        event,
+        ...(commitId ? { commit_id: commitId } : {}),
+        ...(bodyText ? { body: bodyText } : {}),
+        ...(comments.length > 0 ? { comments } : {}),
+    };
+    return { ok: true, payload };
+}
+/**
+ * 422 降级：把行级评注折叠进 review 正文。
+ *
+ * 为什么必须降级而不是直接失败：422 的典型原因是「该行不在 diff 的 RIGHT 侧」
+ * （纯删除行、未变更的上下文行）。内容本身是对的，只是挂不到那一行上——
+ * 丢掉它等于让 Agent 白干一轮，而把内容塞进正文至少保证意见送达。
+ *
+ * 每条降级项都带 `path:line` 前缀，人能在正文里定位；调用方另需回传
+ * `degraded: true` + `degradedReason`，让「这是降级结果」显式可见。
+ */
+export function foldCommentsIntoBody(comments, baseBody) {
+    const head = typeof baseBody === 'string' ? baseBody.trim() : '';
+    const parts = [];
+    if (head)
+        parts.push(head);
+    parts.push('---');
+    parts.push('> ⚠️ 以下评注无法挂到具体代码行（该行不在 diff 的可评论侧），已内联到正文。');
+    for (const c of comments) {
+        const where = c.line ? `${c.path}:${c.line}` : c.path;
+        parts.push(`#### \`${where}\`\n\n${c.body}`);
+    }
+    return parts.join('\n\n');
+}
+/**
+ * 判定失败是否属于「行级评注被拒绝」这一类（值得降级重试）。
+ *
+ * 判据来自 gh 实测 stderr：REST 422 会以 `HTTP 422` 或 `Validation Failed` 出现；
+ * 403/404/网络错误**不在**此列——那些降级也没用，必须原样抛给调用方。
+ */
+export function isLineCommentRejected(errorText) {
+    const t = typeof errorText === 'string' ? errorText : '';
+    if (!t)
+        return false;
+    return /HTTP 422|Validation Failed|Unprocessable Entity/i.test(t);
+}

package/lib/executor/run-log.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 把 gh 的非零退出翻译成给人看的结论；返回 `null` 表示「这是真错误，原样上抛」。
+ *
+ * 两类必须吸收的错误（实测）：
+ * 1. `no failed jobs` —— 工作流本身成功或没有失败步骤，这是确定性答案而非故障；
+ * 2. `Access is denied` —— gh 往本机缓存目录写日志 zip 被系统拒绝，属宿主环境
+ *    问题。原样透传会让调用方（尤其是模型）误判成构建故障，给出自查路径更可行动。
+ *
+ * runId 参与文案：同一个弹窗里可能并排看几个 run，不带编号的报错无法定位。
+ */
+export declare function interpretRunLogError(error: string, runId: string | number): string | null;
+export interface PlainFailureExcerpt {
+    /** 可直接塞进 `<pre>` 的纯文本；空日志时为空串 */
+    text: string;
+    mode: 'anchors' | 'tail' | 'empty';
+    /** 萃取到的失败块总数（可能大于展示的块数） */
+    blockCount: number;
+    droppedBlocks: number;
+    /** 原始日志或二次裁剪是否发生过截断（真值即「结论可能不完整」） */
+    truncated: boolean;
+}
+/**
+ * 把整段日志压成纯文本失败摘要。
+ *
+ * 为什么要有独立的纯文本渲染：弹窗里用 `<pre>` 显示，Markdown 的代码围栏与
+ * 引用块会被当成字面量原样打出来（` ``` ` 出现在日志正文里时更乱）。Markdown 版
+ * 留给 Agent 工具，两者共用同一套锚点萃取与尾部回退，只是排版不同。
+ *
+ * 预算裁剪是**第二道**：gh 侧已按 2MB 截过一次，这里再按 `budget` 裁一次的目的
+ * 是别把几万字塞进 DOM（浏览器渲染与滚动都会明显变卡）。两道截断都必须写进
+ * 返回文本——「没找到更多失败块」与「更多失败块被裁掉了」是相反结论。
+ */
+export declare function buildPlainFailureExcerpt(rawLog: string, opts?: {
+    budget?: number;
+    truncated?: boolean;
+}): PlainFailureExcerpt;

package/lib/executor/run-log.js

@@ -0,0 +1,78 @@
+/**
+ * 失败日志的两个共用件：错误语义映射 + 纯文本锚点摘要。
+ *
+ * 为什么单独成模块而不是各写一遍：
+ * 同一份 `gh run view --log-failed` 输出有两个消费方——Agent 工具（`github_run`
+ * 的 `log_failed`，渲染成 Markdown 进模型上下文）与人在面板里看的 Run 详情弹窗
+ * （渲染成 `<pre>` 纯文本）。两者的**排版**不同，但「什么算失败、哪条是环境故障
+ * 不是构建故障、被截断了必须说明」这三条语义必须一致；各写一份的下场是
+ * Agent 说「没有失败步骤」而弹窗说「拉取失败」。
+ *
+ * 约束：本模块只做纯文本变换，零 I/O、零子进程。真正的 gh 调用留在调用方，
+ * 方便两边各自决定超时与输出预算。
+ */
+import { extractFailureAnchors, tailLines } from './failure-anchors.js';
+/**
+ * 把 gh 的非零退出翻译成给人看的结论；返回 `null` 表示「这是真错误，原样上抛」。
+ *
+ * 两类必须吸收的错误（实测）：
+ * 1. `no failed jobs` —— 工作流本身成功或没有失败步骤，这是确定性答案而非故障；
+ * 2. `Access is denied` —— gh 往本机缓存目录写日志 zip 被系统拒绝，属宿主环境
+ *    问题。原样透传会让调用方（尤其是模型）误判成构建故障，给出自查路径更可行动。
+ *
+ * runId 参与文案：同一个弹窗里可能并排看几个 run，不带编号的报错无法定位。
+ */
+export function interpretRunLogError(error, runId) {
+    const err = String(error || '');
+    if (err.includes('no failed jobs') || err.includes('not failed')) {
+        return `工作流 Run #${runId} 中未检测到任何失败的任务步骤 (状态正常)。`;
+    }
+    if (err.includes('Access is denied') || err.includes('拒绝访问')) {
+        return `无法提取 Run #${runId} 的失败日志：gh CLI 向本机缓存目录写入日志压缩包时被系统拒绝 (${err.trim().slice(0, 200)})。建议检查 gh 缓存目录（如 %LocalAppData%\\GitHub CLI）的写权限后重试，或改用 github_api 拉取日志端点。`;
+    }
+    return null;
+}
+/**
+ * 把整段日志压成纯文本失败摘要。
+ *
+ * 为什么要有独立的纯文本渲染：弹窗里用 `<pre>` 显示，Markdown 的代码围栏与
+ * 引用块会被当成字面量原样打出来（` ``` ` 出现在日志正文里时更乱）。Markdown 版
+ * 留给 Agent 工具，两者共用同一套锚点萃取与尾部回退，只是排版不同。
+ *
+ * 预算裁剪是**第二道**：gh 侧已按 2MB 截过一次，这里再按 `budget` 裁一次的目的
+ * 是别把几万字塞进 DOM（浏览器渲染与滚动都会明显变卡）。两道截断都必须写进
+ * 返回文本——「没找到更多失败块」与「更多失败块被裁掉了」是相反结论。
+ */
+export function buildPlainFailureExcerpt(rawLog, opts = {}) {
+    const budget = Number.isFinite(opts.budget) && opts.budget > 0 ? Math.floor(opts.budget) : 120_000;
+    const src = typeof rawLog === 'string' ? rawLog : '';
+    if (!src.trim()) {
+        return { text: '', mode: 'empty', blockCount: 0, droppedBlocks: 0, truncated: Boolean(opts.truncated) };
+    }
+    const anchored = extractFailureAnchors(src);
+    const mode = anchored.blocks.length > 0 ? 'anchors' : 'tail';
+    const parts = [];
+    if (opts.truncated) {
+        parts.push('⚠️ 原始日志体量超出单次读取上限，以下仅基于已获取的部分。');
+    }
+    if (mode === 'anchors') {
+        parts.push(`共命中 ${anchored.totalBlocks} 个失败块，以下为前 ${anchored.blocks.length} 个：`);
+        anchored.blocks.forEach((b, i) => {
+            parts.push(`\n===== 失败块 ${i + 1}（日志第 ${b.startLine} 行起）=====\n${b.text}`);
+        });
+        if (anchored.droppedBlocks > 0) {
+            parts.push(`\n⚠️ 另有 ${anchored.droppedBlocks} 个失败块未展示（共 ${anchored.totalBlocks} 个），完整日志请在 GitHub 打开。`);
+        }
+    }
+    else {
+        parts.push('未匹配到已知框架的失败锚点，以下为日志尾部 200 行：\n');
+        parts.push(tailLines(src, 200));
+    }
+    let text = parts.join('\n');
+    let truncated = Boolean(opts.truncated);
+    if (text.length > budget) {
+        text = `${text.slice(0, budget)}\n\n⚠️ 摘要已按 ${budget} 字符上限截断，上述失败块可能不完整。`;
+        truncated = true;
+    }
+    return { text, mode, blockCount: anchored.totalBlocks, droppedBlocks: anchored.droppedBlocks, truncated };
+}

package/lib/executor.d.ts

@@ -1,7 +1,8 @@
-import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry, GitBranchesResult, AssociatedRepoItem, PrDetailData, IssueDetailData } from './types.js';
+import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, WorkspaceCleanResult, GitCommitLog, GitCommitEntry, GitBranchesResult, AssociatedRepoItem, PrDetailData, IssueDetailData, RunDetailData, RunLogExcerptData } from './types.js';
 import type { ProxyManager } from './proxy.js';
 import { parseGhVersion, compareGhVersions } from './executor/version-utils.js';
 import { spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput } from './executor/process-utils.js';
+import { type PrReviewResult } 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 type { ParsedGitConfig, ParsedRemote } from './executor/git-parser.js';
 import { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
@@ -14,6 +15,14 @@ export declare class GhExecutor {
     maxOutputChars: number;
     /** UTF-8 字节口径的硬上限；未配置时按 maxOutputChars × 4 推导（覆盖 CJK 3 字节与 emoji 4 字节） */
     maxOutputBytes: number;
+    /**
+     * 累计 gh 子进程调用次数（只增不清零，`run()` 每次 +1）。
+     *
+     * 为什么需要：任务原语（github_task）要如实汇报 `cost.ghCalls`，
+     * 而「原语是否真的比手动串步骤省钱」是这个能力存在的唯一判据。
+     * 消费方用「调用前快照 → 调用后求差」的方式取区间计数。
+     */
+    ghCalls: number;
     /**
      * 列表类查询的默认条数上限。
      * 为什么挂在 executor 而不是给每个工具工厂加 config 参数：executor 是全部
@@ -54,6 +63,44 @@ export declare class GhExecutor {
      * 3. 仅在完全未指定 cwd 且无会话时（全局命令行调用），才兜底回退到最近活跃的 Git 工作区或 process.cwd()。
      */
     resolveWorkspaceCwd(explicitCwd?: string, explicitSessionId?: string): string;
+    /**
+     * 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?: {
+        cwd?: string;
+        sessionId?: string;
+        session?: {
+            id?: string;
+        };
+        agent?: {
+            id?: string;
+        };
+    }): {
+        cwd: string;
+        sessionId?: string;
+    };
     /**
      * 安全执行 gh 命令
      * 采用 execFile 参数数组隔离，彻底杜绝 Shell 字符串拼接注入漏洞
@@ -116,7 +163,7 @@ export declare class GhExecutor {
      * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
      * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
      */
-    getLocalGitStatus(cwd?: string): Promise<GitLocalStatus | null>;
+    getLocalGitStatus(cwd?: string, timeoutMs?: number): Promise<GitLocalStatus | null>;
     /**
      * 分页获取本地未提交文件列表（无网络开销，纯本地毫秒级响应）
      */
@@ -167,18 +214,97 @@ 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、最新提交简述与相对时间。
      * 零网络往返，毫秒级本地管道输出。
      */
     getGitBranches(cwd?: string): Promise<GitBranchesResult | 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。
+     */
+    getReleaseInputs(cwd?: string, fromTagOverride?: string): Promise<{
+        ok: boolean;
+        fromTag: string | null;
+        commits: Array<{
+            sha: string;
+            subject: string;
+            author: string;
+            date: string;
+            body: string;
+        }>;
+        totalCommits: number;
+        error?: string;
+    }>;
+    /**
+     * 工作区干净度闸门（唯一实现）。
+     *
+     * 为什么抽成公共方法：会改变工作区分支/内容的入口有三条——界面切分支（switchGitBranch）、
+     * `github_pr(checkout)`、`github_issue(develop)`。此前只有第一条有脏检查，后两条直穿，
+     * 于是「强阻断」的成文承诺只对界面成立。安全不变量必须只有一处实现。
+     *
+     * 三态语义（fail-closed）：
+     * - `null`（git 读不到）→ 拒绝。读不到状态≠干净，放行等于闸门失效。
+     * - `dirtyCount > 0` → 拒绝，并带前 5 条样例便于用户判断。
+     * - 其余 → 放行。
+     *
+     * 超时为什么单独给 20s：`getLocalGitStatus` 默认 3s 是给概览面板用的（读不到就不渲染那一行），
+     * 但这里是一次安全判决——大型仓库 / 网络盘 / OneDrive 同步目录下 `git status` 冷启动超 3s
+     * 很常见，用 3s 会把"慢"误判成"脏/不可用"，直接把 checkout 挡死。
+     */
+    ensureCleanWorkspace(cwd: string | undefined): Promise<WorkspaceCleanResult>;
     /**
      * 安全切换当前工作区的 Git 分支。
      * 三重安全防御纪律：
      * 1. 目标工作区必须存在有效的 .git 目录；
      * 2. 分支名称严格执行字符白名单校验，防命令行参数注入；
-     * 3. 检查工作区干净度（dirtyCount），若有未提交或未保存的变更直接阻断，杜绝代码被破坏性覆盖。
+     * 3. 工作区干净度交给 ensureCleanWorkspace（唯一实现，与 checkout / develop 共用）。
      */
     switchGitBranch(cwd: string | undefined, branchName: string): Promise<{
         ok: boolean;
@@ -221,6 +347,25 @@ export declare class GhExecutor {
         data?: PrDetailData;
         error?: string;
     }>;
+    /**
+     * 提交带行级评注的 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 正文重试一次。内容不能丢，但降级必须显式可见。
+     */
+    createPrReview(cwd: string | undefined, repo: string | undefined, prNumber: number | string, input: {
+        event?: unknown;
+        body?: unknown;
+        comments?: unknown;
+        commit_id?: unknown;
+    }): Promise<PrReviewResult>;
     /**
      * 获取 Issue 完整详情（供 IssueDetailModal 在线查看消费）。
      *
@@ -236,6 +381,62 @@ export declare class GhExecutor {
         data?: IssueDetailData;
         error?: string;
     }>;
+    /**
+     * 详情类接口的仓库参数归一化（PR / Issue / Run 共用）。
+     *
+     * 返回 `''` = 未传（由本地 remote 决定）；返回 `null` = 非法。
+     *
+     * 为什么要收编三处各自的校验：历史实现各写一份正则，只有 `setDefaultRepo` 额外
+     * 拒绝 `-` 开头与 `..`，其余靠「恒以 `-R <value>` 成对传入」兜底（复核报告 C-13）。
+     * 「成对传入所以安全」是当前调用形状的安全，不是接口的安全——多一处调用方就多
+     * 一次赌。统一到这里后，`-` 开头/`..`/反斜杠在任何详情入口都进不来。
+     */
+    private normalizeRepoFullName;
+    /**
+     * 获取单次 Actions Run 的完整详情（run + jobs + steps）。
+     *
+     * 架构设计：
+     * 1. **run_id 只认纯数字**。它会被当作 `gh run view` 的位置参数拼进 argv，
+     *    不做白名单就等于把「用参数值注入 flag」这条已知缺陷（复核报告 C-01）
+     *    复制到新通道——`--web`、`--log` 都能冒充编号。
+     * 2. 单次往返拿全：`jobs` 里已经包含 steps 树，没有需要并行拉取的第二路。
+     * 3. **日志不在这里拉**。实测单次失败日志 4–40 秒（本机代理下还直接连接重置），
+     *    挂在详情上等于让弹窗首屏去赌网络；日志走 getRunLogExcerpts() 按需拉。
+     */
+    getRunDetail(cwd?: string, runId?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: RunDetailData;
+        error?: string;
+    }>;
+    /**
+     * 按需拉取失败日志并压成纯文本摘要（供 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。
+     */
+    getRunLogExcerpts(cwd?: string, runId?: number | string, jobIds?: Array<number | string>, repo?: string, 
+    /**
+     * 本批日志的总预算（毫秒，默认 `RUN_LOG_TOTAL_BUDGET_MS`）。
+     *
+     * 为什么需要：单 job 超时 60s × 最多 3 个串行 = 最坏 180s。这个调用挂在 HTTP
+     * 路由上，而宿主 WebServer 是全 GUI 共享的——一次点击占住三分钟不可接受。
+     * 超预算的 job 进 `errors[]`（显式、可单独重试），而不是让连接一直挂着。
+     * 允许外部传入只为可测：传 0 能验证「超预算」分支而不必真的等待。
+     */
+    opts?: {
+        totalBudgetMs?: number;
+    }): Promise<{
+        ok: boolean;
+        data?: RunLogExcerptData;
+        error?: string;
+    }>;
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     private getPlatformInstallGuide;
     /**