dsh-github-flow 0.6.0 → 0.7.1

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.d.ts

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

package/lib/tools/agent-task.js

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

package/lib/tools/api.d.ts

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

package/lib/tools/api.js

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