dsh-github-flow 0.6.0 → 0.7.0

package/lib/task-primitives.js

@@ -0,0 +1,194 @@
+/**
+ * 任务级原语的纯函数层：提交归类、SemVer 推导、预算裁剪、信封封装。
+ *
+ * 为什么单独成文件：
+ * 1. 这三个原语的价值是「一轮拿到可执行结论」，结论对不对完全取决于归类与裁剪
+ *    这些纯逻辑——它们必须能脱离网络单测，否则只能靠"跑一次看看"验证；
+ * 2. `cost` 是原语存在的唯一判据（是否真的比手动串步骤省钱），必须由代码计算，
+ *    不能手写常量；
+ * 3. 工具层只负责取数与编排，不承载判定规则。
+ */
+const CC_RE = /^(\w+)(?:\([^)]*\))?(!)?:\s*(.+)$/;
+/**
+ * 按 Conventional Commits 归类提交标题。
+ *
+ * 判定优先级：`!` 破坏性标记 > 类型关键字。为什么先判 `!`：
+ * `feat(api)!: drop v1` 既是 feat 也是 breaking，而它决定的是 **major** 版本，
+ * 归到 feat 会让版本号少跳一级——这是发版事故里最常见的一种。
+ */
+export function classifyCommits(subjects, bodies = []) {
+    const out = { breaking: [], feat: [], fix: [], perf: [], refactor: [], docs: [], other: [] };
+    const list = Array.isArray(subjects) ? subjects : [];
+    list.forEach((raw, i) => {
+        const subject = String(raw ?? '').trim();
+        if (!subject)
+            return;
+        const body = String(bodies[i] ?? '');
+        const m = CC_RE.exec(subject);
+        const type = m ? m[1].toLowerCase() : '';
+        const bang = Boolean(m && m[2]);
+        const isBreaking = bang || /BREAKING[ -]CHANGE/i.test(body);
+        if (isBreaking) {
+            out.breaking.push(subject);
+            return;
+        }
+        if (type === 'feat' || type === 'feature')
+            out.feat.push(subject);
+        else if (type === 'fix' || type === 'bugfix')
+            out.fix.push(subject);
+        else if (type === 'perf')
+            out.perf.push(subject);
+        else if (type === 'refactor')
+            out.refactor.push(subject);
+        else if (type === 'docs' || type === 'doc')
+            out.docs.push(subject);
+        else
+            out.other.push(subject);
+    });
+    return out;
+}
+/** 解析 `v1.2.3` / `1.2.3` / `v1.2.3-rc.1` 形式的版本号 */
+export function parseSemver(tag) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/i.exec(String(tag ?? '').trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+/**
+ * 推导下一个版本号。
+ *
+ * 无 tag 时按 `0.1.0` 起步（而不是 1.0.0）：新仓库的第一个版本不该被当成稳定 API。
+ * `auto` 的判据：breaking → major，feat → minor，其余 → patch。
+ */
+export function suggestVersion(currentTag, groups, bump = 'auto') {
+    const cur = parseSemver(currentTag) || { major: 0, minor: 0, patch: 0 };
+    const hasBreaking = groups.breaking.length > 0;
+    const hasFeat = groups.feat.length > 0;
+    let kind;
+    if (bump !== 'auto')
+        kind = bump;
+    else if (hasBreaking)
+        kind = 'major';
+    else if (hasFeat)
+        kind = 'minor';
+    else
+        kind = 'patch';
+    let next;
+    if (kind === 'major')
+        next = { major: cur.major + 1, minor: 0, patch: 0 };
+    else if (kind === 'minor')
+        next = { major: cur.major, minor: cur.minor + 1, patch: 0 };
+    else
+        next = { major: cur.major, minor: cur.minor, patch: cur.patch + 1 };
+    const reason = bump !== 'auto'
+        ? `按显式指定的 ${bump} 规则递增`
+        : hasBreaking
+            ? `存在 ${groups.breaking.length} 条破坏性变更 → major`
+            : hasFeat
+                ? `存在 ${groups.feat.length} 条新功能 → minor`
+                : `只有修复/其它提交（fix ${groups.fix.length} / perf ${groups.perf.length}）→ patch`;
+    return { version: `${next.major}.${next.minor}.${next.patch}`, bump: kind, reason };
+}
+/**
+ * 按字符预算挑选文件，保证「送进上下文的东西一定装得下」。
+ *
+ * 三条约束：
+ * 1. **按变更量降序**取——大改动更可能是问题的所在，小改动先丢；
+ * 2. 单个文件即使超预算也不硬塞（否则一个超大 diff 会把预算吃光，剩下的文件
+ *    一个都看不到）。超预算的文件只保留 path/增删行数，patch 留空并计入 omitted；
+ * 3. **条目数也要封顶**：60 个文件的元信息本身就有 3–4K 字符，只约束 patch 大小
+ *    等于把「固定开销」排除在预算之外（实测整包因此超预算 4.8K）。超出条目上限的
+ *    文件连元信息都不列，只计入 omitted。
+ */
+export function selectFilesByBudget(files, budgetChars, maxEntries = 40) {
+    const budget = Number.isFinite(budgetChars) && budgetChars > 0 ? Math.floor(budgetChars) : 24_000;
+    const limit = Number.isFinite(maxEntries) && maxEntries > 0 ? Math.floor(maxEntries) : 40;
+    const list = Array.isArray(files) ? [...files] : [];
+    list.sort((a, b) => b.additions + b.deletions - (a.additions + a.deletions));
+    const selected = [];
+    let used = 0;
+    let omitted = 0;
+    for (const f of list) {
+        if (selected.length >= limit) {
+            omitted++;
+            continue;
+        }
+        const patch = typeof f.patch === 'string' ? f.patch : '';
+        const cost = patch.length + f.path.length + 40;
+        if (used + cost > budget) {
+            omitted++;
+            // 元信息仍保留：让调用方知道"还有这些文件"，只是没给正文
+            selected.push({ path: f.path, additions: f.additions, deletions: f.deletions });
+            continue;
+        }
+        used += cost;
+        selected.push(patch ? { ...f, patch } : { path: f.path, additions: f.additions, deletions: f.deletions });
+    }
+    return { selected, omitted, chars: used };
+}
+/**
+ * 封装信封并计算 `cost.chars`。
+ *
+ * `chars` 的口径是**最终返回给模型的那份 JSON 的字符数**（不含 cost 自身，
+ * 否则会自指）。这样「原语是否省钱」才有可比的数字。
+ */
+export function finalizeEnvelope(summary, facts, nextActions, meta) {
+    const payload = {
+        summary,
+        facts,
+        ...(meta.truncated ? { truncated: meta.truncated } : {}),
+        nextActions,
+    };
+    const chars = JSON.stringify(payload).length;
+    return {
+        ...payload,
+        cost: {
+            chars,
+            ghCalls: Math.max(0, Math.floor(meta.ghCalls || 0)),
+            elapsedMs: Math.max(0, Math.floor(meta.elapsedMs || 0)),
+        },
+    };
+}
+/** 从日志片段里抽取 `path:line` 形态的定位锚点（供 diagnose_ci 汇总疑似文件） */
+export function extractFileAnchors(text) {
+    const src = typeof text === 'string' ? text : '';
+    const out = [];
+    const seen = new Set();
+    // 形如 `src/a.ts:12:5` / `app/divide.go:9` / `tests/test_api.py::test_x` 的前两种
+    const re = /(?:^|\s)([\w./\\-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|cpp|c|h|swift|vue|svelte)):(\d+)/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        const file = m[1].replace(/\\/g, '/');
+        const line = Number(m[2]);
+        const key = `${file}:${line}`;
+        if (!Number.isFinite(line) || line <= 0 || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ file, line });
+        if (out.length >= 20)
+            break;
+    }
+    return out;
+}
+/** 把归类结果渲染成 Release notes 草稿（按类型分组，breaking 置顶） */
+export function renderReleaseNotes(version, groups) {
+    const section = (title, items) => items.length > 0 ? `### ${title}\n${items.map((s) => `- ${s}`).join('\n')}` : '';
+    const parts = [`## v${version}`];
+    const breaking = section('⚠️ Breaking Changes', groups.breaking);
+    if (breaking)
+        parts.push(breaking);
+    const feat = section('Features', groups.feat);
+    if (feat)
+        parts.push(feat);
+    const fix = section('Fixes', groups.fix);
+    if (fix)
+        parts.push(fix);
+    const perf = section('Performance', groups.perf);
+    if (perf)
+        parts.push(perf);
+    const rest = [...groups.refactor, ...groups.docs, ...groups.other];
+    const other = section('Others', rest);
+    if (other)
+        parts.push(other);
+    return parts.join('\n\n');
+}

package/lib/tool-tiers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 工具档位（toolsets）+ 只读档位（read_only）。
+ *
+ * 为什么单独成文件：档位与写清单必须是**一张可读的表**。散落在 18 个工具文件里的话，
+ * 「当前到底有哪些工具、哪些是写」就无法一眼回答，也就无法被测试穷举。
+ * 本文件是纯函数 + 纯数据，零 I/O、零依赖，可离线单测。
+ *
+ * 默认零破坏：`toolsets` 缺省 → full 全量 18 个；`read_only` 缺省 → 不剪任何 action。
+ */
+/** 工具的最小结构面（只需要 name / description / parameters 三个字段）。 */
+export interface ToolLike {
+    name: string;
+    description?: string;
+    parameters?: {
+        type?: string;
+        properties?: Record<string, any>;
+        required?: string[];
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+export interface TierConfig {
+    toolsets?: string[];
+    read_only?: boolean;
+}
+/** 预设档位。`full` 不代表具体名单，由 resolveToolNames 特判为「全部」。 */
+export declare const TOOL_PRESETS: Record<string, string[]>;
+/**
+ * 写 action 清单：只读档位下这些 action 会从 enum 里被**注册期剔除**（不是运行时 if）。
+ *
+ * 判定口径：逐个 `case '...'` 分支看它是否产生远端写、本地落盘或不可逆副作用；
+ * 读不准的一律保守归为写（例如 `run download` 会往本地磁盘写文件，计入写）。
+ * `github_api` 记 `'*'`：端点与 method 均可任意，无法降级，只读模式下整体剔除。
+ */
+export declare const WRITE_ACTIONS: Record<string, string[] | '*'>;
+/**
+ * 把 `toolsets` 配置解析成具体工具名清单。
+ *
+ * - `undefined` / 空数组 → 返回 `'all'`（默认全量，零破坏）
+ * - 预设名与裸工具名可混用，取并集
+ * - 未知名字：console.warn 一次并忽略。**不静默**——静默减少工具会让模型
+ *   「看不见工具」却不知道为什么，是比多注册一个工具更难排查的故障。
+ */
+export declare function resolveToolNames(toolsets: string[] | undefined, allNames: string[]): string[] | 'all';
+/**
+ * 按档位裁剪工具列表（纯函数，不修改入参）。
+ *
+ * 只读档位下对**混合工具**剪 action enum 而不是整只剔除：模型在 schema 层就看不到
+ * 写 action，宿主的参数校验会直接拒绝，可审计且不需要运行时分支。
+ */
+export declare function applyTier(tools: ToolLike[], cfg: TierConfig): {
+    kept: ToolLike[];
+    /** 被整体剔除的工具名（只读模式下的 github_api，或档位外的工具） */
+    dropped: string[];
+    /** 被剪掉写 action 的工具名 → 剪掉前的完整 enum（供诊断与测试消费） */
+    pruned: Record<string, string[]>;
+};

package/lib/tool-tiers.js

@@ -0,0 +1,168 @@
+/**
+ * 工具档位（toolsets）+ 只读档位（read_only）。
+ *
+ * 为什么单独成文件：档位与写清单必须是**一张可读的表**。散落在 18 个工具文件里的话，
+ * 「当前到底有哪些工具、哪些是写」就无法一眼回答，也就无法被测试穷举。
+ * 本文件是纯函数 + 纯数据，零 I/O、零依赖，可离线单测。
+ *
+ * 默认零破坏：`toolsets` 缺省 → full 全量 18 个；`read_only` 缺省 → 不剪任何 action。
+ */
+/** 预设档位。`full` 不代表具体名单，由 resolveToolNames 特判为「全部」。 */
+export const TOOL_PRESETS = {
+    full: [],
+    /**
+     * 最小可用面。
+     *
+     * s8 之后 core 的取向变了：**用 3 个任务替代 15 个领域工具**——
+     * `github_task`（审 PR / 诊断 CI / 准备发版）+ `github_repo`（认仓库、读文件）
+     * + `github_help`（查指南）。要细粒度控制时再显式挂 github_pr / github_run。
+     */
+    core: ['github_task', 'github_repo', 'github_help'],
+    /** 流水线值守：CI 诊断与排障所需的只读面更大 */
+    ci: [
+        'github_run', 'github_pr', 'github_issue', 'github_repo',
+        'github_status', 'github_ruleset', 'github_help',
+    ],
+    /** 社区维护：议题/评审/发版/标签/看板 */
+    maintain: [
+        'github_issue', 'github_pr', 'github_label', 'github_release',
+        'github_discussion', 'github_project', 'github_skill', 'github_help',
+    ],
+};
+/**
+ * 写 action 清单：只读档位下这些 action 会从 enum 里被**注册期剔除**（不是运行时 if）。
+ *
+ * 判定口径：逐个 `case '...'` 分支看它是否产生远端写、本地落盘或不可逆副作用；
+ * 读不准的一律保守归为写（例如 `run download` 会往本地磁盘写文件，计入写）。
+ * `github_api` 记 `'*'`：端点与 method 均可任意，无法降级，只读模式下整体剔除。
+ */
+export const WRITE_ACTIONS = {
+    github_pr: ['checkout', 'create', 'review', 'merge', 'ready', 'revert', 'update_branch', 'comment', 'edit'],
+    github_issue: ['create', 'edit', 'develop', 'comment', 'close', 'reopen', 'pin', 'unpin', 'lock', 'unlock', 'delete', 'transfer'],
+    github_run: ['workflow_enable', 'workflow_disable', 'trigger', 'rerun', 'cancel', 'download'],
+    github_repo: ['sync'],
+    github_cache: ['delete'],
+    github_release: ['create', 'upload', 'delete', 'download'],
+    github_secret: ['set', 'delete'],
+    github_label: ['create', 'edit', 'delete', 'clone'],
+    github_gist: ['create', 'edit', 'delete'],
+    github_project: ['item-add', 'item-create', 'item-delete'],
+    github_codespace: ['stop', 'delete'],
+    github_discussion: ['create', 'edit', 'comment'],
+    github_agent_task: ['create'],
+    github_skill: ['install', 'publish', 'update'],
+    // 任务原语里只有 review_pr 会写远端（且需 write+confirm 双门）；diagnose_ci / prepare_release 全只读
+    github_task: ['review_pr'],
+    github_ruleset: [],
+    github_status: [],
+    github_help: [],
+    github_api: '*',
+};
+/**
+ * 把 `toolsets` 配置解析成具体工具名清单。
+ *
+ * - `undefined` / 空数组 → 返回 `'all'`（默认全量，零破坏）
+ * - 预设名与裸工具名可混用，取并集
+ * - 未知名字：console.warn 一次并忽略。**不静默**——静默减少工具会让模型
+ *   「看不见工具」却不知道为什么，是比多注册一个工具更难排查的故障。
+ */
+export function resolveToolNames(toolsets, allNames) {
+    if (!toolsets || toolsets.length === 0)
+        return 'all';
+    const picked = new Set();
+    const unknown = [];
+    for (const raw of toolsets) {
+        const name = typeof raw === 'string' ? raw.trim() : '';
+        if (!name)
+            continue;
+        const preset = TOOL_PRESETS[name];
+        if (preset) {
+            if (name === 'full')
+                return 'all';
+            for (const t of preset)
+                picked.add(t);
+            continue;
+        }
+        if (allNames.includes(name)) {
+            picked.add(name);
+            continue;
+        }
+        unknown.push(name);
+    }
+    if (unknown.length > 0) {
+        console.warn(`[dsh-github-flow] toolsets 中存在未知档位/工具名：${unknown.join(', ')}。` +
+            `可用档位：${Object.keys(TOOL_PRESETS).join(' / ')}；也可直接写工具名（如 github_pr）。已忽略未知项。`);
+    }
+    // 过滤掉本版本不存在的预设成员（预设表可能超前于实际注册的工具）
+    return allNames.filter((n) => picked.has(n));
+}
+/**
+ * 按档位裁剪工具列表（纯函数，不修改入参）。
+ *
+ * 只读档位下对**混合工具**剪 action enum 而不是整只剔除：模型在 schema 层就看不到
+ * 写 action，宿主的参数校验会直接拒绝，可审计且不需要运行时分支。
+ */
+export function applyTier(tools, cfg) {
+    const allNames = tools.map((t) => t.name);
+    const names = resolveToolNames(cfg.toolsets, allNames);
+    let kept = names === 'all' ? [...tools] : tools.filter((t) => names.includes(t.name));
+    const dropped = allNames.filter((n) => !kept.some((t) => t.name === n));
+    const pruned = {};
+    if (cfg.read_only !== true)
+        return { kept, dropped, pruned };
+    const readOnlyKept = [];
+    for (const tool of kept) {
+        const writes = WRITE_ACTIONS[tool.name] ?? [];
+        if (writes === '*') {
+            dropped.push(tool.name);
+            continue;
+        }
+        const params = tool.parameters;
+        const actionSchema = params?.properties?.action;
+        if (!params || !Array.isArray(actionSchema?.enum) || writes.length === 0) {
+            // 没有 action 维度的工具（github_help / github_status / github_ruleset）原样保留
+            readOnlyKept.push(tool);
+            continue;
+        }
+        const keptEnum = actionSchema.enum.filter((a) => !writes.includes(a));
+        if (keptEnum.length === 0) {
+            // 整只工具都是写操作 → 剔除，而不是留一个空 enum
+            dropped.push(tool.name);
+            continue;
+        }
+        pruned[tool.name] = [...actionSchema.enum];
+        const allowed = new Set(keptEnum);
+        readOnlyKept.push({
+            ...tool,
+            description: `[只读模式] ${tool.description ?? ''}`.trim(),
+            parameters: {
+                ...params,
+                properties: {
+                    ...params.properties,
+                    action: { ...actionSchema, enum: keptEnum },
+                },
+            },
+            /**
+             * 只读档位的**执行期**拦截。
+             *
+             * 为什么剪了 enum 还要再拦一次：本插件的工具是手写 descriptor，不是
+             * `defineTool` 产物——宿主只把 parameters 当 JSON Schema 发给模型，**不做执行前
+             * 参数校验**。所以模型只要发出一个被剪掉的 action（最常见的是从历史消息里复读，
+             * 或用户手工构造），执行路径会照常走到 `gh pr merge`。实测确认过：
+             * `applyTier([pr], {read_only:true})` 之后调 `{action:'merge', confirm:true}`
+             * 仍然会真的发起合并。只剪 schema 等于只做了「看不见」，没做「做不到」。
+             *
+             * 位置在闸门之外（applyTier 在工厂 wrapWithGate 之后套），所以先拒只读违规，
+             * 再走 confirm 闸门。
+             */
+            async execute(args, ctx) {
+                const action = args?.action;
+                if (typeof action === 'string' && !allowed.has(action)) {
+                    throw new Error(`只读模式（read_only: true）下 ${tool.name} 不允许 action "${action}"；可用: ${keptEnum.join(' / ')}`);
+                }
+                return tool.execute(args, ctx);
+            },
+        });
+    }
+    return { kept: readOnlyKept, dropped, pruned };
+}

package/lib/tools/agent-task.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderAgentTaskMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
@@ -10,7 +11,7 @@ function normalizeOutput(data) {
 }
 const AGENT_TASK_JSON_FIELDS = 'completedAt,createdAt,id,name,pullRequestNumber,pullRequestState,pullRequestTitle,pullRequestUrl,repository,state,updatedAt,user';
 export function createAgentTaskTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_agent_task',
         description: '管理 GitHub Copilot Coding Agent 云端智能体任务会话：查看已分派任务列表、检视任务状态与会话日志、向云端智能体发起新编码与重构任务。基于 gh CLI preview 特性。',
         parameters: {
@@ -59,8 +60,7 @@ export function createAgentTaskTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             const repoArgs = args.repo ? ['-R', args.repo] : [];
             const runOpts = { cwd, sessionId };
             switch (args.action) {
@@ -131,5 +131,5 @@ export function createAgentTaskTool(executor) {
                     throw new Error(`未知的 Agent Task 操作: ${args.action}`);
             }
         },
-    };
+    });
 }

package/lib/tools/api.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -8,7 +9,7 @@ function normalizeOutput(data) {
     return { result: data !== undefined && data !== null ? data : '' };
 }
 export function createApiTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_api',
         description: '通过 GitHub CLI 认证环境直接调用任意 GitHub REST 或 GraphQL API 端点（兜底逃生门）。支持 --jq 过滤；fields 一律按字面字符串传参，避免 gh 的 -F 类型转换改写请求体。',
         parameters: {
@@ -57,13 +58,24 @@ export function createApiTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
-            const cmd = ['api', args.endpoint];
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
+            // schema 声明了 required: ['endpoint']，但宿主校验不一定兜住（模型可能传空串）。
+            // 不校验时 `gh api ""` 退出码 0 并返回整个 API 索引 JSON，模型会误以为"查到了数据"。
+            const endpoint = typeof args.endpoint === 'string' ? args.endpoint.trim() : '';
+            if (!endpoint) {
+                throw new Error('endpoint 为必填参数：请传入 REST 路径（如 "repos/owner/repo/pulls" 或 "user"）或 graphql 查询。');
+            }
+            // 只拒绝以 - 开头的形态：那才是真正的注入面（会被 gh 当成 flag 吃掉）。
+            // 注意不要要求"必须含 /"——`user` / `rate_limit` / `notifications` 都是合法单段端点，
+            // 实测 `gh api user --jq .login` 正常返回；按"/"判形态会误杀这些合法调用。
+            if (endpoint.startsWith('-')) {
+                throw new Error(`endpoint 不能以 - 开头（会被 gh 当作命令行 flag）："${endpoint}"。`);
+            }
+            const cmd = ['api', endpoint];
             // gh api 默认在提供 -f/-F 时会自动将 HTTP 方法隐式切换为 POST。
             // 若调用方未指定 method，且 endpoint 不是以 graphql 开头，则按契约默认为 GET。
             // 必须显式传入 -X，防止带有 fields 参数的 GET 请求被 gh 自动改写为 POST 导致 422 报错。
-            const isGraphql = typeof args.endpoint === 'string' && args.endpoint.trim().toLowerCase().startsWith('graphql');
+            const isGraphql = endpoint.toLowerCase().startsWith('graphql');
             const method = args.method || (isGraphql ? 'POST' : 'GET');
             cmd.push('-X', method);
             if (args.jq) {
@@ -97,5 +109,5 @@ export function createApiTool(executor) {
                 throw new Error(res.error);
             return normalizeOutput(res.data !== undefined ? res.data : res.rawOutput);
         },
-    };
+    });
 }

package/lib/tools/cache.js

@@ -1,3 +1,4 @@
+import { wrapWithGate } from '../destructive.js';
 import { renderCacheMarkdown } from '../renderers/markdown.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
@@ -9,9 +10,9 @@ function normalizeOutput(data) {
     return { result: data !== undefined && data !== null ? data : '' };
 }
 export function createCacheTool(executor) {
-    return {
+    return wrapWithGate({
         name: 'github_cache',
-        description: '管理 GitHub Actions 构建缓存 (Caches)：查看缓存列表与占用容量、按 ID 或 Key 删除指定缓存、以及全量清空仓库缓存。全量清空不可逆，需 confirm: true。',
+        description: '管理 GitHub Actions 构建缓存 (Caches)：查看缓存列表与占用容量、按 ID 或 Key 删除指定缓存、以及全量清空仓库缓存。删除不可逆，delete 的三种方式（cache_id / key / all）均需 confirm: true。',
         parameters: {
             type: 'object',
             properties: {
@@ -56,7 +57,7 @@ export function createCacheTool(executor) {
                 },
                 confirm: {
                     type: 'boolean',
-                    description: '高危破坏性操作确认标志（delete 当 all: true 时必需）。未传 true 时输出影响评估报告并拦截。',
+                    description: '高危破坏性操作确认标志（delete 的三态 cache_id / key / all 均必需）。未传 true 时输出影响评估报告并拦截。',
                 },
             },
             required: ['action'],
@@ -68,8 +69,7 @@ export function createCacheTool(executor) {
             },
         },
         async execute(args, execContext) {
-            const cwd = execContext?.cwd || process.cwd();
-            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const { cwd, sessionId } = executor.resolveExecScope(execContext);
             let repoTarget = args.repo;
             if (!repoTarget) {
                 const meta = await executor.getRepoMetadata(cwd, sessionId);
@@ -120,19 +120,26 @@ export function createCacheTool(executor) {
                     return normalizeOutput(rawData || []);
                 }
                 case 'delete': {
-                    // 1. 全量清空分支
-                    if (args.all === true) {
-                        if (args.confirm !== true) {
-                            return {
-                                status: 'AWAITING_CONFIRMATION',
-                                action: 'delete',
-                                all: true,
-                                repo: repoTarget,
-                                warning: `⚠️ 高危破坏性操作：即将清空仓库 ${repoTarget} 的所有 GitHub Actions 构建缓存`,
-                                impact: `清空缓存不可逆，会导致后续流水线构建无法复用依赖与构建产物，显著增加 CI 运行耗时。`,
-                                requiredAction: `如确认彻底清空，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_cache(action: 'delete', all: true, confirm: true)\``,
-                            };
-                        }
+                    // ---- 第一段：选择器归一化 + 形态校验（在任何执行之前）----
+                    const hasAll = args.all === true;
+                    const cacheIdStr = args.cache_id !== undefined && args.cache_id !== null ? String(args.cache_id).trim() : '';
+                    const keyStr = args.key !== undefined && args.key !== null ? String(args.key).trim() : '';
+                    const hasId = cacheIdStr !== '';
+                    const hasKey = keyStr !== '';
+                    if (!hasAll && !hasId && !hasKey) {
+                        throw new Error('删除缓存时必须指定 `cache_id`、`key` 或 `all: true`（三条删除分支均需配合 confirm: true）。');
+                    }
+                    // 形态校验必须先于执行：不校验时 `cache_id: "--all"` 会被当作 flag 透传，
+                    // 等价于清空全仓缓存；而 `gh cache delete --all` 自身没有二次确认，绕过即秒清。
+                    if (hasId && !/^\d+$/.test(cacheIdStr)) {
+                        throw new Error(`cache_id 必须是纯数字的缓存 ID（实际收到 "${cacheIdStr}"）。按 key 删除请改用 key 参数，全量清空请用 all: true。`);
+                    }
+                    if (hasKey && (keyStr.startsWith('-') || keyStr.length > 512)) {
+                        throw new Error('key 不能以 - 开头（防被当作命令行 flag），且长度不得超过 512 字符。');
+                    }
+                    // ---- 执行段（argv 形状与改动前保持一致）----
+                    // confirm 闸门由 wrapWithGate 在工厂入口统一处理，三条分支共用同一套语义。
+                    if (hasAll) {
                         const delCmd = ['cache', 'delete', '--all', '--succeed-on-no-caches', ...repoArgs];
                         if (args.ref) {
                             delCmd.push('-r', String(args.ref));
@@ -147,40 +154,35 @@ export function createCacheTool(executor) {
                             detail: res.rawOutput || '',
                         };
                     }
-                    // 2. 按 cache_id 删除
-                    if (args.cache_id !== undefined && args.cache_id !== null && String(args.cache_id).trim() !== '') {
-                        const delCmd = ['cache', 'delete', String(args.cache_id), ...repoArgs];
+                    if (hasId) {
+                        const delCmd = ['cache', 'delete', cacheIdStr, ...repoArgs];
                         const res = await executor.run(delCmd, runOpts);
                         if (!res.ok)
                             throw new Error(res.error);
                         return {
                             success: true,
-                            cache_id: String(args.cache_id),
-                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 ID 为 "${args.cache_id}" 的 Actions 缓存`,
+                            cache_id: cacheIdStr,
+                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 ID 为 "${cacheIdStr}" 的 Actions 缓存`,
                             detail: res.rawOutput || '',
                         };
                     }
-                    // 3. 按 key 删除
-                    if (args.key !== undefined && args.key !== null && String(args.key).trim() !== '') {
-                        const delCmd = ['cache', 'delete', String(args.key), ...repoArgs];
-                        if (args.ref) {
-                            delCmd.push('-r', String(args.ref));
-                        }
-                        const res = await executor.run(delCmd, runOpts);
-                        if (!res.ok)
-                            throw new Error(res.error);
-                        return {
-                            success: true,
-                            key: String(args.key),
-                            message: `🗑️ 成功删除仓库 ${repoTarget} 中 Key 为 "${args.key}" 的 Actions 缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
-                            detail: res.rawOutput || '',
-                        };
+                    const delCmd = ['cache', 'delete', keyStr, ...repoArgs];
+                    if (args.ref) {
+                        delCmd.push('-r', String(args.ref));
                     }
-                    throw new Error('删除缓存时必须指定 `cache_id`、`key` 或 `all: true`（全量删除需配合 confirm: true）。');
+                    const res = await executor.run(delCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        key: keyStr,
+                        message: `🗑️ 成功删除仓库 ${repoTarget} 中 Key 为 "${keyStr}" 的 Actions 缓存` + (args.ref ? ` (Ref: ${args.ref})` : ''),
+                        detail: res.rawOutput || '',
+                    };
                 }
                 default:
                     throw new Error(`不支持的 cache 操作: "${args.action}"。可选值: list, delete。`);
             }
         },
-    };
+    });
 }