dsh-github-flow 0.6.0 → 0.7.1

package/lib/destructive.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 破坏性操作声明表 + 统一闸门。
+ *
+ * 为什么要有这张表：同一个「拦截 → 返回影响评估 → 要求 confirm: true」的模式在
+ * 16 个 (工具, action) 上各写了一遍。任何一处忘写就是漏洞，而漏洞是**看不见的**
+ * （工具照常返回成功，没人知道本该拦一次）。表化之后「没有条目 = 没有闸门」可以
+ * 一眼审完，并且能被测试穷举。
+ *
+ * 拦截点收在一处实现（`wrapWithGate`），由每个工具的工厂函数返回时套上——见文件末尾该函数的注释。`src/tools/` 里不再保留任何一行闸门代码。
+ *
+ * ⚠️ 与旧实现的一处已知差异：`cache delete` / `issue transfer` / `label delete` 的
+ * 旧文案里内插了**运行时解析出的仓库名**（`repoTarget`）。注册期拿不到它（要额外打
+ * 一次 `gh repo view`），因此文案改为不内插仓库名。渲染层只消费
+ * warning/impact/requiredAction 三个字段，不消费 repo，故输出形态无变化。
+ */
+/** 闸门状态字面量的唯一来源：工具层与渲染层都引用它，不再各写一遍字符串。 */
+export declare const GATE_BLOCKED: 'AWAITING_CONFIRMATION';
+export interface GatePayload {
+    status: typeof GATE_BLOCKED;
+    warning: string;
+    impact: string;
+    requiredAction: string;
+    /** 部分工具额外回显的定位字段（action / name / gist_id / cache_id / key / all） */
+    [key: string]: unknown;
+}
+interface GateSpec {
+    /**
+     * 命中条件。缺省 = 该 action 恒拦。
+     *
+     * 为什么需要这个字段：`release upload` 只在 clobber 时危险、`skill publish` 只在
+     * 正式发布时危险。条件写进表里，过滤逻辑就不再散落在各工具的分支里。
+     * 同时用它表达「原实现里位于闸门之前的必填校验」——否则一个缺参数的调用会先拿到
+     * 「请确认」而不是本该拿到的「必须提供 xxx」，那是行为回退。
+     */
+    when?: (args: any) => boolean;
+    describe(args: any): GatePayload;
+}
+export declare const DESTRUCTIVE_ACTIONS: Record<string, Record<string, GateSpec>>;
+/**
+ * 统一闸门：命中则返回拦截载荷，否则返回 undefined。
+ *
+ * `confirm === true` 的判定放在这里而不是每个 describe 里——15 份重复的
+ * `if (args.confirm !== true)` 正是这次要消掉的东西。
+ */
+export declare function guardDestructive(toolName: string, args: any): GatePayload | undefined;
+/**
+ * 用闸门包一层 execute（注册期唯一入口）。
+ *
+ * 为什么包在注册期而不是 `executor.run()`：`run()` 只看得见 argv，看不见
+ * `action` / `confirm` 语义。把语义解析塞进 argv 层就是把简单问题复杂化。
+ *
+ * 保持 `name` / `description` / `parameters` / `output` 原样，只替换 `execute`，
+ * 宿主侧的 schema 校验与渲染链路完全不受影响。
+ */
+export declare function wrapWithGate<T extends {
+    name: string;
+    execute: (...a: any[]) => any;
+}>(tool: T): T;
+export {};

package/lib/destructive.js

@@ -0,0 +1,285 @@
+/**
+ * 破坏性操作声明表 + 统一闸门。
+ *
+ * 为什么要有这张表：同一个「拦截 → 返回影响评估 → 要求 confirm: true」的模式在
+ * 16 个 (工具, action) 上各写了一遍。任何一处忘写就是漏洞，而漏洞是**看不见的**
+ * （工具照常返回成功，没人知道本该拦一次）。表化之后「没有条目 = 没有闸门」可以
+ * 一眼审完，并且能被测试穷举。
+ *
+ * 拦截点收在一处实现（`wrapWithGate`），由每个工具的工厂函数返回时套上——见文件末尾该函数的注释。`src/tools/` 里不再保留任何一行闸门代码。
+ *
+ * ⚠️ 与旧实现的一处已知差异：`cache delete` / `issue transfer` / `label delete` 的
+ * 旧文案里内插了**运行时解析出的仓库名**（`repoTarget`）。注册期拿不到它（要额外打
+ * 一次 `gh repo view`），因此文案改为不内插仓库名。渲染层只消费
+ * warning/impact/requiredAction 三个字段，不消费 repo，故输出形态无变化。
+ */
+/** 闸门状态字面量的唯一来源：工具层与渲染层都引用它，不再各写一遍字符串。 */
+export const GATE_BLOCKED = 'AWAITING_CONFIRMATION';
+const str = (v) => (v === undefined || v === null ? '' : String(v).trim());
+/** 有值即认为「调用方已经给到了定位参数」，可以进入拦截而不是先报缺参。 */
+const has = (v) => str(v) !== '';
+export const DESTRUCTIVE_ACTIONS = {
+    github_pr: {
+        // 默认检出不带 -f；只有显式 force 才需要二次确认（会丢弃本地未推送提交）
+        checkout: {
+            when: (a) => a.force === true,
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ force 会把本地分支重置到 PR #${str(a.pr_number)} 的最新状态，丢弃本地未推送的提交。`,
+                impact: '重置后本地分支与 PR 头一致，本地独有提交只能通过 git reflog 找回。',
+                requiredAction: '如确认重置，请附加 `force: true, confirm: true` 重新调用。',
+            }),
+        },
+        merge: {
+            // 缺 pr_number 时旧实现先抛「merge 操作必须提供 pr_number」；闸门前移后必须自己把
+            // 这条前置校验编码进 when，否则会返回一个「PR #」空号的确认载荷（实测）。
+            when: (a) => has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将合并 PR #${str(a.pr_number)}（合并策略: ${a.merge_method || 'squash'}${a.delete_branch ? '，且删除源分支' : ''}）。`,
+                impact: '合并操作将直接向基准分支写入代码并更新远端 PR 状态。',
+                requiredAction: '如确认执行合并，请向用户明确确认并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        revert: {
+            when: (a) => has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将对 PR #${str(a.pr_number)} 创建反向提交（revert）。`,
+                impact: '将在远端创建反向提交并生成新的 revert PR——这是新增远端实体，不是本地操作。',
+                requiredAction: '如确认执行，请向用户明确确认并附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_issue: {
+        close: {
+            // 缺 issue_number 时旧实现先抛「close 操作必须提供 issue_number」
+            when: (a) => has(a.issue_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将关闭 Issue #${str(a.issue_number)}。`,
+                impact: '关闭后该议题状态将变更为 CLOSED，请与用户确认是否确实已解决或需要关闭。',
+                requiredAction: '如确认关闭，请在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+        delete: {
+            // 缺 issue_number 时旧实现先抛「delete 操作必须提供 issue_number」
+            when: (a) => has(a.issue_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将**物理删除** Issue #${str(a.issue_number)}（非 close，不可恢复）。`,
+                impact: 'Issue 编号将永久消失，全部评论与附件随之湮灭，GraphQL 层无法恢复——这与 close（可 reopen 逆转）有本质区别。',
+                requiredAction: '如确认删除，请与用户核实后附加 `confirm: true` 重新调用。',
+            }),
+        },
+        transfer: {
+            // 旧实现按 issue_number → target_repo → 同仓 的顺序抛错；前两条要在这里保住，
+            // 同仓校验依赖运行时解析出的 repoTarget，只能在工具内（confirm 之后）暴露。
+            when: (a) => has(a.issue_number) && has(a.target_repo),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将把 Issue #${str(a.issue_number)} 迁移到 ${str(a.target_repo)}。`,
+                impact: `迁移后 Issue 归属 ${str(a.target_repo)}（原 URL 301 重定向），标签/里程碑不随迁，操作不可静默撤回。需要目标仓库的写权限。`,
+                requiredAction: '如确认迁移，请与用户核实后附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_release: {
+        // 原实现先校验 tag / assets 再判 clobber，条件里一并带上，避免缺参时先拿到确认提示
+        upload: {
+            when: (a) => a.clobber === true && has(a.tag) && Array.isArray(a.assets) && a.assets.length > 0,
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将覆盖上传 Release ${str(a.tag)} 的同名旧资产（clobber 模式）。`,
+                impact: 'clobber 会先删除既有同名资产再上传；若上传中途失败，旧资产已丢失且无法恢复。',
+                requiredAction: '如确认覆盖，请向用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        delete: {
+            when: (a) => has(a.tag),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 高危操作拦截：你即将删除 Release ${str(a.tag)}${a.cleanup_tag ? ' 及其 Git Tag' : ''}。`,
+                impact: '删除 Release 不可逆；若同时清理 Tag，引用该 Tag 的历史版本入口将全部失效。',
+                requiredAction: '如确认删除，请与用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_secret: {
+        delete: {
+            when: (a) => has(a.name),
+            describe: (a) => {
+                // 与旧实现同口径：kind === 'variable' 时按 Variable 措辞，否则按 Secret
+                const isVariable = a.kind === 'variable';
+                const kindLabel = isVariable ? 'Variable' : 'Secret';
+                return {
+                    status: GATE_BLOCKED,
+                    warning: `⚠️ 高危操作拦截：你即将删除 ${kindLabel}「${str(a.name)}」${a.org ? `（组织 ${str(a.org)}）` : ''}。`,
+                    impact: isVariable
+                        ? '删除后所有引用该变量的工作流将取不到值，运行中的构建立即失败。'
+                        : '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
+                    requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
+                };
+            },
+        },
+    },
+    github_label: {
+        delete: {
+            when: (a) => has(a.name),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                action: 'delete',
+                name: a.name,
+                warning: `⚠️ 高危破坏性操作：即将删除仓库标签 "${str(a.name)}"`,
+                impact: '删除标签不可逆，且会导致目标仓库内所有已打上该标签的 Issue 与 PR 自动解绑该标记。',
+                requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_label(action: 'delete', name: '${str(a.name)}', confirm: true)\``,
+            }),
+        },
+    },
+    github_cache: {
+        // 三条删除分支共用一套 confirm 语义。选择器缺失时原实现会抛「必须指定…」，
+        // 这里 predicate 为 false，把精确报错留给工具本体，不用泛化文案顶替。
+        delete: {
+            when: (a) => a.all === true || has(a.cache_id) || has(a.key),
+            describe: (a) => {
+                const cacheIdStr = str(a.cache_id);
+                const keyStr = str(a.key);
+                const hasAll = a.all === true;
+                // 分支判定与工具本体的归一化同口径：cache_id 非空即按 ID 删除，否则按 key
+                const byId = cacheIdStr !== '';
+                const targetDesc = hasAll
+                    ? '清空该仓库的所有 GitHub Actions 构建缓存'
+                    : byId
+                        ? `删除仓库中 ID 为 "${cacheIdStr}" 的构建缓存`
+                        : `删除仓库中 Key 为 "${keyStr}" 的构建缓存`;
+                return {
+                    status: GATE_BLOCKED,
+                    action: 'delete',
+                    ...(hasAll ? { all: true } : byId ? { cache_id: cacheIdStr } : { key: keyStr }),
+                    warning: `⚠️ 高危破坏性操作：即将${targetDesc}`,
+                    impact: '删除构建缓存不可逆，会导致后续流水线构建无法复用依赖与构建产物，显著增加 CI 运行耗时。',
+                    requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+                };
+            },
+        },
+    },
+    github_codespace: {
+        delete: {
+            when: (a) => has(a.codespace),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 销毁确认拦截：你即将永久删除云端开发环境「${str(a.codespace)}」。`,
+                impact: '物理销毁 Codespace 将永久释放云端计算资源，环境中任何未提交并推送到远端 Git 的临时修改都将无法找回。',
+                requiredAction: '如确认销毁该实例，请核对环境名称并在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_gist: {
+        delete: {
+            when: (a) => has(a.gist_id),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                action: 'delete',
+                gist_id: str(a.gist_id),
+                warning: `⚠️ 高危破坏性操作：即将永久删除 Gist 代码片段 "${str(a.gist_id)}"`,
+                impact: '删除 Gist 为物理删除，无法通过 GitHub API 恢复，所有引用该 Gist URL 的外部链接将失效并返回 404。',
+                requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_gist(action: 'delete', gist_id: '${str(a.gist_id)}', confirm: true)\``,
+            }),
+        },
+    },
+    github_project: {
+        'item-delete': {
+            when: (a) => has(a.item_id),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 删除确认拦截：你即将从看板中删除条目（ID: ${str(a.item_id)}）。`,
+                impact: '该操作将从项目看板中物理移除该条目（若是关联的 Issue/PR，实体不会被删除，仅解除看板关联）。',
+                requiredAction: '如确认删除，请在参数中附加 `confirm: true` 重新调用。',
+            }),
+        },
+    },
+    github_skill: {
+        install: {
+            when: (a) => has(a.repository),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 安装确认拦截：你即将从仓库「${str(a.repository)}」安装 Skill${a.skill_name ? `「${str(a.skill_name)}」` : ''}到本地${a.scope === 'user' ? '用户主目录（全局）' : '当前项目'}。`,
+                impact: '安装会在本地磁盘写入 SKILL.md 及附属文件，并可能影响目标 Agent 宿主的默认行为。',
+                requiredAction: '如确认安装，请向用户核实并附加 `confirm: true` 重新调用。',
+            }),
+        },
+        // 只在「正式发布」分支拦截：dry_run 缺省为真（预演），fix 模式也是本地产物修复。
+        // 原实现先校验 tag，这里一并带上，缺 tag 仍由工具本体抛出「必须提供版本 tag」。
+        publish: {
+            when: (a) => a.dry_run === false && a.fix !== true && has(a.tag),
+            describe: (a) => {
+                const cleanTag = str(a.tag);
+                return {
+                    status: GATE_BLOCKED,
+                    warning: `⚠️ 发布确认拦截：你即将正式发布 Agent Skill 并创建 GitHub Release（Tag: ${cleanTag}）。`,
+                    impact: `该操作将在仓库中打上「agent-skills」Topic、创建 Git Tag「${cleanTag}」并发布正式 GitHub Release，向所有用户公开提供该版本。`,
+                    requiredAction: `如确认发布，请核实版本号并在参数中附加 \`confirm: true\` 重新调用。`,
+                };
+            },
+        },
+    },
+    /*
+     * 任务级原语（s8）：默认只读，唯一会写远端的是 review_pr 的 write 模式。
+     *
+     * 为什么 when 要判 `write === true`：`review_pr` 默认只产出上下文包（不写回），
+     * 若恒拦，Agent 连"看一眼这个 PR 该审什么"都要先确认一次，闸门就变成了噪音。
+     */
+    github_task: {
+        review_pr: {
+            when: (a) => a.write === true && has(a.pr_number),
+            describe: (a) => ({
+                status: GATE_BLOCKED,
+                warning: `⚠️ 写回拦截：你即将向 PR #${str(a.pr_number)} 提交一条公开可见的 Review（含行级评注）。`,
+                impact: '该 Review 会立即出现在 PR 时间线上并通知相关人，删除只能逐条进行。',
+                requiredAction: '如确认写回，请附加 `write: true, confirm: true` 重新调用；只想看结论请去掉 `write`。',
+            }),
+        },
+    },
+};
+/**
+ * 统一闸门：命中则返回拦截载荷，否则返回 undefined。
+ *
+ * `confirm === true` 的判定放在这里而不是每个 describe 里——15 份重复的
+ * `if (args.confirm !== true)` 正是这次要消掉的东西。
+ */
+export function guardDestructive(toolName, args) {
+    const table = DESTRUCTIVE_ACTIONS[toolName];
+    if (!table)
+        return undefined;
+    const action = typeof args?.action === 'string' ? args.action : '';
+    // 必须挡原型链：`action: "toString"` 会让 table[action] 命中原型上的函数，
+    // spec.describe 不是函数直接 TypeError（复核报告 C-05，11 工具 × 16 组合全崩）。
+    const spec = Object.prototype.hasOwnProperty.call(table, action) ? table[action] : undefined;
+    if (!spec)
+        return undefined;
+    if (args?.confirm === true)
+        return undefined;
+    if (spec.when && !spec.when(args))
+        return undefined;
+    return spec.describe(args);
+}
+/**
+ * 用闸门包一层 execute（注册期唯一入口）。
+ *
+ * 为什么包在注册期而不是 `executor.run()`：`run()` 只看得见 argv，看不见
+ * `action` / `confirm` 语义。把语义解析塞进 argv 层就是把简单问题复杂化。
+ *
+ * 保持 `name` / `description` / `parameters` / `output` 原样，只替换 `execute`，
+ * 宿主侧的 schema 校验与渲染链路完全不受影响。
+ */
+export function wrapWithGate(tool) {
+    return {
+        ...tool,
+        async execute(args, ctx) {
+            const gate = guardDestructive(tool.name, args);
+            if (gate)
+                return gate;
+            return tool.execute(args, ctx);
+        },
+    };
+}

package/lib/executor/args-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * gh argv 的「位置参数」守卫。
+ *
+ * 为什么需要它：`gh` 用 cobra/pflag 解析 argv，"以 - 开头的 token" 一律优先当
+ * 选项。工具把用户输入直接 push 成**位置参数**时，`pr_number: "--force"` 会变成
+ * `gh pr checkout --force`——破坏性闸门判的是**参数**，而危险在 **argv**，
+ * 两者不在同一层（复核报告 C-01 的三条绕过全是这个形状）。
+ *
+ * 为什么只拒绝 `-` 开头而不是做全量字符白名单：
+ * 各工具的位置参数语义差异很大（编号是数字、名字是任意非空串、路径可以有斜杠），
+ * 统一白名单会误伤合法输入；而"不能是选项"是所有位置参数**共有**的唯一硬约束。
+ * 具体格式（正整数 / owner-repo / 数字 ID）仍由各工具自己的校验负责。
+ *
+ * 空值不在此处报错：调用方各自的「必须提供 X」文案更准确，这里越俎代庖会把
+ * 两个不同原因的错误合并成一个，反而降低可诊断性。
+ */
+export declare function assertPositionArg(value: unknown, label: string): string;

package/lib/executor/args-guard.js

@@ -0,0 +1,23 @@
+/**
+ * gh argv 的「位置参数」守卫。
+ *
+ * 为什么需要它：`gh` 用 cobra/pflag 解析 argv，"以 - 开头的 token" 一律优先当
+ * 选项。工具把用户输入直接 push 成**位置参数**时，`pr_number: "--force"` 会变成
+ * `gh pr checkout --force`——破坏性闸门判的是**参数**，而危险在 **argv**，
+ * 两者不在同一层（复核报告 C-01 的三条绕过全是这个形状）。
+ *
+ * 为什么只拒绝 `-` 开头而不是做全量字符白名单：
+ * 各工具的位置参数语义差异很大（编号是数字、名字是任意非空串、路径可以有斜杠），
+ * 统一白名单会误伤合法输入；而"不能是选项"是所有位置参数**共有**的唯一硬约束。
+ * 具体格式（正整数 / owner-repo / 数字 ID）仍由各工具自己的校验负责。
+ *
+ * 空值不在此处报错：调用方各自的「必须提供 X」文案更准确，这里越俎代庖会把
+ * 两个不同原因的错误合并成一个，反而降低可诊断性。
+ */
+export function assertPositionArg(value, label) {
+    const raw = typeof value === 'number' ? String(value) : String(value ?? '').trim();
+    if (raw.startsWith('-')) {
+        throw new Error(`${label} 非法：位置参数不能以 "-" 开头（收到 "${raw}"），它会被 gh 当成命令行选项而不是取值。`);
+    }
+    return raw;
+}

package/lib/executor/failure-anchors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CI 失败日志的「锚点萃取」：把整段日志压成若干段带行号的失败上下文。
+ *
+ * 为什么需要它：
+ * 1. 矩阵构建（matrix）下一个 run 会有 N 个 job 的失败日志，动辄几万行；
+ *    「整段给模型」必然触顶默认输出上限，而截断发生在**萃取之前**——
+ *    结果就是 Agent 只能看到前 24KB，后面的失败根本不存在于上下文里；
+ * 2. 模型真正需要的不是全量日志，而是「每个失败的起点 + 之后几十行」；
+ * 3. 锚点全部取自各框架日志的首列特征（实测输出），不含猜测。
+ *
+ * 纯函数、零 I/O：日志文本进，结构化块出。
+ */
+/** 去掉 gh 的 `job\tstep\ttimestamp ` 前缀（没有前缀时原样返回） */
+export declare function stripLogPrefix(line: string): string;
+export interface FailureBlock {
+    /** 命中的锚点原文（去掉首尾空白，超长截断） */
+    anchor: string;
+    /** 该块起始行号（1-based，方便人去日志里定位） */
+    startLine: number;
+    /** 块正文（含锚点行与其后上下文） */
+    text: string;
+}
+export interface FailureAnchorResult {
+    blocks: FailureBlock[];
+    /** 萃取到的失败块总数（可能大于返回的 blocks.length） */
+    totalBlocks: number;
+    /** 因 maxBlocks 上限被丢弃的块数 */
+    droppedBlocks: number;
+}
+export interface FailureAnchorOptions {
+    /** 每个锚点向后取多少行上下文 */
+    radius?: number;
+    /** 最多返回多少块 */
+    maxBlocks?: number;
+}
+/**
+ * 从日志文本中萃取失败块。
+ *
+ * 合并规则：相邻锚点相距不超过 `radius` 行时并入同一块——同一个异常常常先打
+ * `FAIL` 再打 `AssertionError`，拆成两块等于把一次失败说两遍。
+ * 每块长度上限 `2*radius+1` 行，保证单块不会因为连续堆栈而无限膨胀。
+ */
+export declare function extractFailureAnchors(text: string, options?: FailureAnchorOptions): FailureAnchorResult;
+/** 把萃取结果渲染成 Markdown（人可读、模型可读，行号显式） */
+export declare function renderFailureAnchors(result: FailureAnchorResult): string;
+/**
+ * 无锚点时的回退：取尾部若干行。
+ *
+ * 为什么取尾部而不是头部：日志的失败结论在末尾（构建工具通常先刷编译输出、
+ * 最后才打印错误汇总），取头部基本只能拿到环境准备信息。
+ */
+export declare function tailLines(text: string, count?: number): string;

package/lib/executor/failure-anchors.js

@@ -0,0 +1,116 @@
+/**
+ * CI 失败日志的「锚点萃取」：把整段日志压成若干段带行号的失败上下文。
+ *
+ * 为什么需要它：
+ * 1. 矩阵构建（matrix）下一个 run 会有 N 个 job 的失败日志，动辄几万行；
+ *    「整段给模型」必然触顶默认输出上限，而截断发生在**萃取之前**——
+ *    结果就是 Agent 只能看到前 24KB，后面的失败根本不存在于上下文里；
+ * 2. 模型真正需要的不是全量日志，而是「每个失败的起点 + 之后几十行」；
+ * 3. 锚点全部取自各框架日志的首列特征（实测输出），不含猜测。
+ *
+ * 纯函数、零 I/O：日志文本进，结构化块出。
+ */
+/**
+ * 锚点识别（行首特征）。
+ *
+ * 为什么分两条正则：
+ * 多数框架的失败标记在**行首**（pytest 的 `FAILED path::test`、node 的
+ * `AssertionError`、Go 的 `panic:`），但 TypeScript 编译器的真实输出是
+ * `src/file.ts(3,5): error TS2322: ...` —— 前面带 `文件(行,列):` 前缀，
+ * 行首锚定会一条都命中不了。所以 TS 单独用「行内出现」判定。
+ *
+ * `❌` 单列：本项目自己的 CI 测试输出就是 `❌ FAIL: xxx`，不加这一条
+ * 等于对自己仓库的失败日志完全失明。
+ */
+const ANCHOR_LINE_RE = /^(?:FAIL|FAILED|ERROR|--- FAIL|AssertionError|Error:|panic:|Traceback \(most recent call last\)|npm ERR!|✖|❌)/;
+const ANCHOR_INLINE_RE = /\berror TS\d+:/;
+/**
+ * `gh run view --log-failed` 的每行前缀：`<job>\t<step>\t<ISO8601>Z <正文>`。
+ *
+ * 这是**实测**出来的（不是猜的）：不打掉这个前缀，所有行首都变成 job 名，
+ * 上面两条正则一条也命中不了——锚点萃取会整体退化成「尾部 200 行回退」，
+ * 功能等于不存在。剥离只用于**匹配**，块正文仍保留原始行（job/step 是有用上下文）。
+ */
+const GH_LOG_PREFIX_RE = /^[^\t]*\t[^\t]*\t\d{4}-\d{2}-\d{2}T[0-9:.]+Z\s?/;
+/** 去掉 gh 的 `job\tstep\ttimestamp ` 前缀（没有前缀时原样返回） */
+export function stripLogPrefix(line) {
+    const src = typeof line === 'string' ? line : '';
+    const m = GH_LOG_PREFIX_RE.exec(src);
+    return m ? src.slice(m[0].length) : src;
+}
+/**
+ * 从日志文本中萃取失败块。
+ *
+ * 合并规则：相邻锚点相距不超过 `radius` 行时并入同一块——同一个异常常常先打
+ * `FAIL` 再打 `AssertionError`，拆成两块等于把一次失败说两遍。
+ * 每块长度上限 `2*radius+1` 行，保证单块不会因为连续堆栈而无限膨胀。
+ */
+export function extractFailureAnchors(text, options = {}) {
+    const radius = Number.isFinite(options.radius) && options.radius > 0 ? Math.floor(options.radius) : 15;
+    const maxBlocks = Number.isFinite(options.maxBlocks) && options.maxBlocks > 0 ? Math.floor(options.maxBlocks) : 8;
+    const src = typeof text === 'string' ? text : '';
+    if (!src)
+        return { blocks: [], totalBlocks: 0, droppedBlocks: 0 };
+    const lines = src.split(/\r?\n/);
+    const anchors = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // 先剥 gh 的 job/step/timestamp 前缀，再按行首特征匹配（见 GH_LOG_PREFIX_RE 注释）
+        const body = stripLogPrefix(line).trim();
+        if (ANCHOR_LINE_RE.test(body) || ANCHOR_INLINE_RE.test(body))
+            anchors.push(i);
+    }
+    if (anchors.length === 0)
+        return { blocks: [], totalBlocks: 0, droppedBlocks: 0 };
+    // 分组：相邻锚点间距 > radius 才开新块
+    const groups = [];
+    for (const idx of anchors) {
+        const cur = groups[groups.length - 1];
+        if (!cur || idx - cur.last > radius)
+            groups.push({ start: idx, last: idx });
+        else
+            cur.last = idx;
+    }
+    const maxLines = 2 * radius + 1;
+    const all = groups.map((g) => {
+        const end = Math.min(lines.length, g.last + radius + 1);
+        const slice = lines.slice(g.start, end).slice(0, maxLines);
+        const anchorRaw = lines[g.start].trim();
+        return {
+            anchor: anchorRaw.length > 160 ? anchorRaw.slice(0, 160) + '…' : anchorRaw,
+            startLine: g.start + 1,
+            text: slice.join('\n'),
+        };
+    });
+    const blocks = all.slice(0, maxBlocks);
+    return { blocks, totalBlocks: all.length, droppedBlocks: all.length - blocks.length };
+}
+/** 把萃取结果渲染成 Markdown（人可读、模型可读，行号显式） */
+export function renderFailureAnchors(result) {
+    if (!result || result.blocks.length === 0)
+        return '';
+    const parts = [];
+    parts.push(`**共命中 ${result.totalBlocks} 个失败块**，以下为前 ${result.blocks.length} 个：`);
+    result.blocks.forEach((b, i) => {
+        parts.push(`\n### 失败块 ${i + 1}（日志第 ${b.startLine} 行起）\n\`\`\`\n${b.text}\n\`\`\``);
+    });
+    if (result.droppedBlocks > 0) {
+        parts.push(`\n> ⚠️ 已省略 ${result.droppedBlocks} 个失败块（共 ${result.totalBlocks} 个）。需要时可用更小的范围重跑，或到 Actions 页面查看完整日志。`);
+    }
+    return parts.join('\n');
+}
+/**
+ * 无锚点时的回退：取尾部若干行。
+ *
+ * 为什么取尾部而不是头部：日志的失败结论在末尾（构建工具通常先刷编译输出、
+ * 最后才打印错误汇总），取头部基本只能拿到环境准备信息。
+ */
+export function tailLines(text, count = 200) {
+    const src = typeof text === 'string' ? text : '';
+    if (!src)
+        return '';
+    const lines = src.split(/\r?\n/);
+    if (lines.length <= count)
+        return src;
+    return lines.slice(lines.length - count).join('\n');
+}

package/lib/executor/pr-review.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 文档字段构造请求体，未自造任何键。
+ */
+/** 单次 review 的行级评注上限。超过就拆多次，一次一个请求 = 通知只发一轮 */
+export declare const MAX_REVIEW_COMMENTS = 50;
+export type PrReviewEvent = 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
+/** 调用方传入的单条行级评注（宽松类型，校验后才是 REST 形状） */
+export interface PrReviewCommentInput {
+    path?: unknown;
+    line?: unknown;
+    side?: unknown;
+    start_line?: unknown;
+    start_side?: unknown;
+    body?: unknown;
+}
+/** REST 形状的单条评注（全部字段已归一化） */
+export interface PrReviewCommentPayload {
+    path: string;
+    line?: number;
+    side?: 'LEFT' | 'RIGHT';
+    start_line?: number;
+    start_side?: 'LEFT' | 'RIGHT';
+    /**
+     * `file` = 文件级评论（不挂行），`line` = 行级评论。
+     *
+     * 为什么需要它：REST 的 `comments[]` 里 `line` 是**实际必填**的（缺了就 422），
+     * 想只评论某个文件必须显式声明 `subject_type: 'file'`。不写这个字段时，
+     * 「只给 path 不给 line」会被 GitHub 判为非法行级评论——那正是「明明参数合法却 422」的成因。
+     */
+    subject_type?: 'file' | 'line';
+    body: string;
+}
+/** REST 形状的 review 请求体 */
+export interface PrReviewPayload {
+    commit_id?: string;
+    event: PrReviewEvent;
+    body?: string;
+    comments?: PrReviewCommentPayload[];
+}
+export interface BuildResult {
+    ok: boolean;
+    payload?: PrReviewPayload;
+    /** 校验失败时的**全部**问题（一次说完，不要让调用方改一条试一次） */
+    errors?: string[];
+}
+/** `createPrReview` 的返回形状 */
+export interface PrReviewResult {
+    ok: boolean;
+    error?: string;
+    /** 是否走了 422 降级（行级评注被折叠进正文） */
+    degraded?: boolean;
+    /** 降级原因，供渲染层用 appendDegradedNote 显式呈现 */
+    degradedReason?: string;
+    data?: any;
+}
+/**
+ * 构造 REST review 请求体。
+ *
+ * @param input.event    review 判定，缺省 COMMENT
+ * @param input.body     整体说明
+ * @param input.comments 行级评注（空数组等价于不传 → 调用方应走原 gh pr review 路径）
+ * @param input.commit_id 可选锚点 SHA
+ */
+export declare function buildPrReviewPayload(input: {
+    event?: unknown;
+    body?: unknown;
+    comments?: unknown;
+    commit_id?: unknown;
+}): BuildResult;
+/**
+ * 422 降级：把行级评注折叠进 review 正文。
+ *
+ * 为什么必须降级而不是直接失败：422 的典型原因是「该行不在 diff 的 RIGHT 侧」
+ * （纯删除行、未变更的上下文行）。内容本身是对的，只是挂不到那一行上——
+ * 丢掉它等于让 Agent 白干一轮，而把内容塞进正文至少保证意见送达。
+ *
+ * 每条降级项都带 `path:line` 前缀，人能在正文里定位；调用方另需回传
+ * `degraded: true` + `degradedReason`，让「这是降级结果」显式可见。
+ */
+export declare function foldCommentsIntoBody(comments: PrReviewCommentPayload[], baseBody?: string): string;
+/**
+ * 判定失败是否属于「行级评注被拒绝」这一类（值得降级重试）。
+ *
+ * 判据来自 gh 实测 stderr：REST 422 会以 `HTTP 422` 或 `Validation Failed` 出现；
+ * 403/404/网络错误**不在**此列——那些降级也没用，必须原样抛给调用方。
+ */
+export declare function isLineCommentRejected(errorText: string): boolean;