minimal-agent 0.10.0 → 0.12.0

package/src/tools/agent/worktree.ts

@@ -0,0 +1,296 @@
+/**
+ * ============================================================
+ *  src/tools/agent/worktree.ts —— 子 agent 的 git worktree 隔离助手
+ * ------------------------------------------------------------
+ *  搬自 Claude Code 官方 utils/worktree.ts 的核心路径（createAgentWorktree
+ *  那条**无全局状态**的路径——并行子 agent 不能共享单例 session 状态），
+ *  砍掉 settings/hooks/tmux/sparse-checkout/symlink 等锦上添花件。
+ *
+ *  保留的官方实战经验（每条都对应真实事故教训）：
+ *    - slug 白名单校验：slug 会被拼进目录路径与分支名，防路径穿越。
+ *    - `git worktree add -B`（大写 B）：上次目录被删但分支残留时强制重置，
+ *      免去额外的 git branch -D 前置清理。
+ *    - fail-closed 改动判定：任何 git 命令失败一律视为「有改动」，宁可多留
+ *      一个 worktree，绝不误删并行子 agent 的工作成果。
+ *    - 清理序列：worktree remove --force → 等 100ms 锁释放 → branch -D；
+ *      清理失败只记日志不抛——绝不让清理问题卡死主流程。
+ *    - GIT_TERMINAL_PROMPT=0 + stdin ignore：防 git/ssh 弹交互式凭证输入挂死。
+ *
+ *  目录选址 `<gitRoot>/.agent-worktrees/`：刻意避开 `.minimal-agent*` 保留前缀
+ *  （/new 会按前缀整目录 rm -rf，直接删 worktree 目录会留下悬空的 git 注册项）；
+ *  首次创建时追加进 `<gitdir>/info/exclude`（仓库本地 ignore，不污染共享 .gitignore）。
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+import { appendFile, readFile, writeFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { dlog } from '../../utils/debugLog.js';
+
+const WORKTREES_DIR = '.agent-worktrees';
+
+interface GitResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+/** 跑一条 git 命令（防挂死 env + stdin ignore），spawn 失败也归一成 ok:false。 */
+async function runGit(args: string[], cwd: string): Promise<GitResult> {
+  return new Promise((resolve) => {
+    const child = spawn('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '' },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d: Buffer) => { stdout += d.toString('utf8'); });
+    child.stderr.on('data', (d: Buffer) => { stderr += d.toString('utf8'); });
+    child.on('error', (e) => resolve({ ok: false, stdout, stderr: String(e) }));
+    child.on('close', (code) =>
+      resolve({ ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim() }),
+    );
+  });
+}
+
+/** slug 白名单（官方同款语义）：会拼进路径和分支名，只放行安全字符。 */
+export function validateSlug(slug: string): boolean {
+  return /^[a-zA-Z0-9._-]{1,64}$/.test(slug) && slug !== '.' && slug !== '..';
+}
+
+export interface AgentWorktree {
+  ok: true;
+  /** worktree 目录绝对路径 */
+  path: string;
+  /** 临时分支名（agent/<slug>） */
+  branch: string;
+  /** 创建时刻的基线提交（改动判定 / diff 摘要的锚点） */
+  baseSha: string;
+  /** 主仓库根 */
+  gitRoot: string;
+}
+
+export type CreateWorktreeResult = AgentWorktree | { ok: false; error: string };
+
+/** 把 worktree 目录加进仓库本地 ignore（best-effort，失败静默——只是降噪）。 */
+async function ensureLocalExclude(cwd: string): Promise<void> {
+  try {
+    const r = await runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+    if (!r.ok || !r.stdout) return;
+    const excludePath = join(r.stdout, 'info', 'exclude');
+    const line = `${WORKTREES_DIR}/`;
+    const existing = await readFile(excludePath, 'utf8').catch(() => '');
+    if (existing.split(/\r?\n/).includes(line)) return;
+    await appendFile(excludePath, `${existing.endsWith('\n') || existing === '' ? '' : '\n'}${line}\n`);
+  } catch {
+    /* ignore 失败只影响 git status 观感，不影响功能 */
+  }
+}
+
+/**
+ * 在当前仓库创建一个子 agent 专用 worktree（基于 HEAD 的独立分支）。
+ * 非 git 仓库 / 无提交仓库返回 ok:false——把决策权交回主 agent（降级无隔离或串行）。
+ */
+export async function createAgentWorktree(
+  slug: string,
+  fromCwd: string = getWorkingDir(),
+): Promise<CreateWorktreeResult> {
+  if (!validateSlug(slug)) {
+    return { ok: false, error: `非法的 worktree 名称「${slug}」（只允许字母数字._-，≤64 字符）` };
+  }
+  const root = await runGit(['rev-parse', '--show-toplevel'], fromCwd);
+  if (!root.ok || !root.stdout) {
+    return { ok: false, error: '当前目录不是 git 仓库，无法创建 worktree 隔离' };
+  }
+  const gitRoot = root.stdout;
+  const head = await runGit(['rev-parse', 'HEAD'], gitRoot);
+  if (!head.ok || !head.stdout) {
+    return { ok: false, error: '仓库还没有任何提交（HEAD 不存在），无法创建 worktree——先 git commit 一次' };
+  }
+  const baseSha = head.stdout;
+  const path = join(gitRoot, WORKTREES_DIR, slug);
+  const branch = `agent/${slug}`;
+
+  await ensureLocalExclude(gitRoot);
+
+  const add = await runGit(['worktree', 'add', '-B', branch, path, 'HEAD'], gitRoot);
+  if (!add.ok) {
+    return { ok: false, error: `git worktree add 失败：${add.stderr || add.stdout}` };
+  }
+  return { ok: true, path, branch, baseSha, gitRoot };
+}
+
+/**
+ * worktree 相对基线是否有改动（未提交文件 或 新增提交）。
+ * fail-closed：任何 git 命令失败一律返回 true（有改动）——宁多留不误删。
+ */
+export async function hasWorktreeChanges(path: string, baseSha: string): Promise<boolean> {
+  const status = await runGit(['status', '--porcelain'], path);
+  if (!status.ok) return true;
+  if (status.stdout.length > 0) return true;
+  const revList = await runGit(['rev-list', '--count', `${baseSha}..HEAD`], path);
+  if (!revList.ok) return true;
+  return Number.parseInt(revList.stdout, 10) > 0;
+}
+
+/** 相对基线的 diff 摘要（best-effort，失败返回空串）——给主 agent 收口审阅用。 */
+export async function worktreeDiffStat(path: string, baseSha: string): Promise<string> {
+  const diff = await runGit(['diff', '--stat', baseSha], path);
+  const parts: string[] = [];
+  if (diff.ok && diff.stdout) parts.push(diff.stdout);
+  // diff --stat 看不到未跟踪的新文件，用 status 补上
+  const status = await runGit(['status', '--porcelain'], path);
+  if (status.ok && status.stdout) {
+    const untracked = status.stdout
+      .split('\n')
+      .filter((l) => l.startsWith('??'))
+      .map((l) => `  新文件（未跟踪）: ${l.slice(3)}`);
+    if (untracked.length > 0) parts.push(untracked.join('\n'));
+  }
+  return parts.join('\n');
+}
+
+/**
+ * 把 worktree 里的未提交改动确定性提交到临时分支（幂等：无改动直接 ok）。
+ * 为什么需要：子 agent 用 Edit/Write 改文件后通常**不会** git commit——
+ * 分支上没有提交的话，主 agent 收口时 `git merge` 合不到任何东西（改动只活在
+ * worktree 工作区里）。收尾时由引擎代提交，不依赖模型自觉。
+ * -c 内联身份兜底：机器没配 user.name/email 也能提交（squash 合并时最终
+ * 提交人仍是用户自己，临时分支上的作者名无所谓）。
+ */
+export async function commitWorktreeChanges(
+  path: string,
+  message: string,
+): Promise<{ ok: boolean; error?: string }> {
+  const status = await runGit(['status', '--porcelain'], path);
+  if (status.ok && status.stdout.length === 0) return { ok: true };
+  if (status.ok) {
+    const sensitive = status.stdout.split('\n').map((line) => line.slice(3).trim()).filter(isSensitiveWorktreePath);
+    if (sensitive.length > 0) {
+      return { ok: false, error: `拒绝自动提交敏感文件：${sensitive.join(', ')}` };
+    }
+  }
+  const add = await runGit(['add', '-A'], path);
+  if (!add.ok) return { ok: false, error: add.stderr || add.stdout };
+  const commit = await runGit(
+    [
+      '-c', 'user.name=minimal-agent',
+      '-c', 'user.email=agent@minimal-agent.local',
+      'commit', '-m', message,
+    ],
+    path,
+  );
+  if (!commit.ok) return { ok: false, error: commit.stderr || commit.stdout };
+  return { ok: true };
+}
+
+function isSensitiveWorktreePath(path: string): boolean {
+  const normalized = path.replaceAll('\\', '/').toLowerCase();
+  const base = normalized.split('/').at(-1) ?? normalized;
+  return base === '.env' || base.startsWith('.env.') || normalized.includes('/.ssh/') ||
+    /(^|\/)(credentials?|secrets?)(\.|\/|$)/.test(normalized) ||
+    /\.(pem|key|p12|pfx|jks|keystore)$/.test(base) || base === 'id_rsa' || base === 'id_ed25519';
+}
+
+export async function worktreeChangedFiles(path: string, baseSha: string): Promise<string[]> {
+  const result = await runGit(['diff', '--name-only', baseSha], path);
+  const status = await runGit(['status', '--porcelain'], path);
+  const files = new Set<string>();
+  if (result.ok) for (const row of result.stdout.split('\n')) if (row.trim()) files.add(row.trim());
+  if (status.ok) for (const row of status.stdout.split('\n')) if (row.length > 3) files.add(row.slice(3).trim());
+  return [...files].sort();
+}
+
+/**
+ * 清理 worktree 目录 + 临时分支。尽力而为：失败只记 debug 日志，不抛——
+ * 清理残留可由用户随时 `git worktree remove` / `git branch -D` 手动处理。
+ */
+export async function removeAgentWorktree(
+  path: string,
+  branch: string,
+  gitRoot: string,
+): Promise<void> {
+  const rm = await runGit(['worktree', 'remove', '--force', path], gitRoot);
+  if (!rm.ok) dlog('agent', 'worktree remove 失败', { path, err: rm.stderr });
+  // 官方经验：remove 后立即 branch -D 偶发撞锁，等 100ms 释放
+  await new Promise((r) => setTimeout(r, 100));
+  const del = await runGit(['branch', '-D', branch], gitRoot);
+  if (!del.ok) dlog('agent', 'worktree 分支删除失败', { branch, err: del.stderr });
+}
+
+export interface AgentWorktreeDiff {
+  id: string;
+  branch: string;
+  baseSha: string;
+  diff: string;
+  changedFiles: string[];
+}
+
+async function resolveManagedWorktree(cwd: string, id: string): Promise<AgentWorktree | { ok: false; error: string }> {
+  if (!validateSlug(id)) return { ok: false, error: '非法的子任务 ID' };
+  const root = await runGit(['rev-parse', '--show-toplevel'], cwd);
+  if (!root.ok || !root.stdout) return { ok: false, error: '当前目录不是 Git 仓库' };
+  const path = join(root.stdout, WORKTREES_DIR, id);
+  const branch = `agent/${id}`;
+  const base = await runGit(['merge-base', branch, 'HEAD'], root.stdout);
+  if (!base.ok || !base.stdout) return { ok: false, error: '未找到该隔离子任务' };
+  return { ok: true, path, branch, baseSha: base.stdout, gitRoot: root.stdout };
+}
+
+export async function inspectAgentWorktree(cwd: string, id: string): Promise<AgentWorktreeDiff | { error: string }> {
+  const wt = await resolveManagedWorktree(cwd, id);
+  if (!wt.ok) return { error: wt.error };
+  const diff = await runGit(['diff', '--binary', wt.baseSha, wt.branch], wt.gitRoot);
+  if (!diff.ok) return { error: diff.stderr || '读取差异失败' };
+  const status = await runGit(['status', '--short'], wt.path);
+  const pending = status.ok && status.stdout
+    ? `\n\n尚未提交的隔离工作区改动（不会自动应用）：\n${status.stdout}`
+    : '';
+  return {
+    id,
+    branch: wt.branch,
+    baseSha: wt.baseSha,
+    diff: `${diff.stdout}${pending}`.trim(),
+    changedFiles: await worktreeChangedFiles(wt.path, wt.baseSha),
+  };
+}
+
+export async function applyAgentWorktree(cwd: string, id: string): Promise<{ ok: boolean; error?: string }> {
+  const wt = await resolveManagedWorktree(cwd, id);
+  if (!wt.ok) return wt;
+  const worktreeStatus = await runGit(['status', '--porcelain'], wt.path);
+  if (!worktreeStatus.ok) return { ok: false, error: '无法确认隔离工作区状态，已停止自动应用' };
+  if (worktreeStatus.stdout) {
+    return {
+      ok: false,
+      error: '隔离工作区仍有未提交改动（可能包含被安全策略拒绝提交的文件），为防止丢失，不能自动应用或清理',
+    };
+  }
+  const head = await runGit(['rev-parse', 'HEAD'], wt.gitRoot);
+  if (!head.ok || head.stdout !== wt.baseSha) return { ok: false, error: '当前 HEAD 已变化，不能安全应用；请先人工审阅和同步分支' };
+  const diff = await runGit(['diff', '--binary', wt.baseSha, wt.branch], wt.gitRoot);
+  if (!diff.ok) return { ok: false, error: diff.stderr || '生成差异失败' };
+  if (!diff.stdout) { await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot); return { ok: true }; }
+  const patchFile = join(wt.gitRoot, '.git', `minimal-agent-${process.pid}-${Date.now()}.patch`);
+  try {
+    // runGit 会 trim 文本输出；git apply 要求补丁保留终止换行。
+    await writeFile(patchFile, `${diff.stdout}\n`, { mode: 0o600 });
+    const check = await runGit(['apply', '--check', patchFile], wt.gitRoot);
+    if (!check.ok) return { ok: false, error: `变更检查失败：${check.stderr || check.stdout}` };
+    const apply = await runGit(['apply', patchFile], wt.gitRoot);
+    if (!apply.ok) return { ok: false, error: `应用变更失败：${apply.stderr || apply.stdout}` };
+    await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+    return { ok: true };
+  } finally {
+    await unlink(patchFile).catch(() => {});
+  }
+}
+
+export async function discardAgentWorktree(cwd: string, id: string): Promise<{ ok: boolean; error?: string }> {
+  const wt = await resolveManagedWorktree(cwd, id);
+  if (!wt.ok) return wt;
+  await removeAgentWorktree(wt.path, wt.branch, wt.gitRoot);
+  return { ok: true };
+}

package/src/tools/ask/ask.js

@@ -20,6 +20,7 @@ const optionSchema = z.object({
     label: z
         .string()
         .min(1)
+        .max(40)
         .describe('选项显示文本（简洁）；把推荐项放第一个，并在其 label 末尾标「(推荐)」'),
     description: z
         .string()
@@ -31,6 +32,7 @@ const questionSchema = z.object({
     header: z
         .string()
         .min(1)
+        .max(12, 'header 最多 12 个字符')
         .describe('问题的短标签（≤12 字），如「交互底座」「鉴权方式」'),
     multiSelect: z
         .boolean()
@@ -49,6 +51,21 @@ const inputSchema = z.object({
         .max(4) // 与工具描述/UI 上限硬对齐：超发在参数校验层被拒（模型拿 Zod 错误自纠），
         // 避免「TUI 静默截断到 4 题 vs 非交互全部自动作答」的行为分叉
         .describe('1-4 个问题（通常 1 个；确需一次问多件事时才多个）'),
+}).superRefine((value, context) => {
+    const questions = new Set();
+    value.questions.forEach((question, questionIndex) => {
+        if (questions.has(question.question)) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['questions', questionIndex, 'question'], message: '问题文本不能重复' });
+        }
+        questions.add(question.question);
+        const labels = new Set();
+        question.options.forEach((option, optionIndex) => {
+            if (labels.has(option.label)) {
+                context.addIssue({ code: z.ZodIssueCode.custom, path: ['questions', questionIndex, 'options', optionIndex, 'label'], message: '同一问题的选项标签不能重复' });
+            }
+            labels.add(option.label);
+        });
+    });
 });
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
 const parameters = toToolParameters(inputSchema);

package/src/tools/ask/ask.ts

@@ -0,0 +1,122 @@
+/**
+ * ============================================================
+ *  src/tools/ask/ask.ts —— AskUserQuestion 工具（向用户提结构化选择题）
+ * ------------------------------------------------------------
+ *  对齐上游 Claude Code 的 AskUserQuestion：让模型在「需要用户拍板」时停下来问，
+ *  而不是替用户瞎猜。它本身只是一个普通工具 —— call() 调 askBridge 的
+ *  requestUserChoice()，TUI 弹选择界面、用户选完把答案当 tool_result 喂回模型。
+ *  「等用户」= 这个工具返回得慢；非交互宿主（-p/gateway）自动选推荐项（见 askBridge）。
+ *
+ *  这一个工具同时让主循环 / workflow（tool: AskUserQuestion）/ agent: 节点
+ *  都获得「问用户」的能力 —— 动态工作流的交互底座。
+ * ============================================================
+ */
+
+import { z } from 'zod';
+
+import { requestUserChoice } from '../../askBridge.js';
+import type { Tool, ToolResult } from '../../types.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+// ---------------- 1. Zod 输入 schema ----------------
+const optionSchema = z.object({
+  label: z
+    .string()
+    .min(1)
+    .max(40)
+    .describe('选项显示文本（简洁）；把推荐项放第一个，并在其 label 末尾标「(推荐)」'),
+  description: z
+    .string()
+    .optional()
+    .describe('该选项的说明 / 取舍，帮用户理解后果'),
+});
+
+const questionSchema = z.object({
+  question: z.string().min(1).describe('要问用户的完整问题'),
+  header: z
+    .string()
+    .min(1)
+    .max(12, 'header 最多 12 个字符')
+    .describe('问题的短标签（≤12 字），如「交互底座」「鉴权方式」'),
+  multiSelect: z
+    .boolean()
+    .optional()
+    .describe('是否允许多选；默认 false（单选）'),
+  options: z
+    .array(optionSchema)
+    .min(2)
+    .max(4)
+    .describe('2-4 个互斥选项；第一个应为你的推荐项'),
+});
+
+const inputSchema = z.object({
+  questions: z
+    .array(questionSchema)
+    .min(1)
+    .max(4) // 与工具描述/UI 上限硬对齐：超发在参数校验层被拒（模型拿 Zod 错误自纠），
+    // 避免「TUI 静默截断到 4 题 vs 非交互全部自动作答」的行为分叉
+    .describe('1-4 个问题（通常 1 个；确需一次问多件事时才多个）'),
+}).superRefine((value, context) => {
+  const questions = new Set<string>();
+  value.questions.forEach((question, questionIndex) => {
+    if (questions.has(question.question)) {
+      context.addIssue({ code: z.ZodIssueCode.custom, path: ['questions', questionIndex, 'question'], message: '问题文本不能重复' });
+    }
+    questions.add(question.question);
+    const labels = new Set<string>();
+    question.options.forEach((option, optionIndex) => {
+      if (labels.has(option.label)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ['questions', questionIndex, 'options', optionIndex, 'label'], message: '同一问题的选项标签不能重复' });
+      }
+      labels.add(option.label);
+    });
+  });
+});
+type AskInput = z.infer<typeof inputSchema>;
+
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description（指导模型何时/如何用） ----------------
+const description = `向用户提出结构化的选择题（最多 4 题，每题 2-4 个选项），用于需要用户做决定的场合。
+使用时机：
+- 需求 / 方案有取舍、没有绝对对错（多个合理方案各有利弊）→ 让用户拍板；
+- 关键信息缺失或模糊、继续做风险大 → 让用户补充。
+不要用于：你自己能从代码 / 上下文 / 常识判断出答案的问题（那样只会打断用户）。
+约定：每题第一个选项放你的推荐，并在其 label 末尾标「(推荐)」。
+界面会自动附带「其他（自由输入）」逃生项，**无需**你手动加。
+返回值是用户的选择文本，据此继续。`;
+
+// ---------------- 4. call() ----------------
+async function call(input: AskInput, signal?: AbortSignal): Promise<ToolResult> {
+  try {
+    const answers = await requestUserChoice(input.questions, signal);
+    const lines: string[] = ['用户已回答 AskUserQuestion：', ''];
+    answers.forEach((a, i) => {
+      lines.push(`Q${i + 1} [${a.header}] ${a.question}`);
+      lines.push(`A${i + 1}: ${a.selected.join('、') || '(未选)'}`);
+      lines.push('');
+    });
+    return { ok: true, content: lines.join('\n').trimEnd() };
+  } catch (e) {
+    // 提问被 reject → 当普通工具失败喂回。注意：TUI 里 ESC 经 App 的
+    // onCancel={chat.abort} 中断**整轮**（喂回后 loop 见 signal.aborted 收口
+    // interrupted，模型不会继续）；「让模型换思路」只在宿主 reject 单个提问
+    // 而不中断整轮时成立（workflow onError / 非 TUI 宿主自定义 handler）。
+    return { ok: false, error: `提问被取消 / 中断：${(e as Error).message}` };
+  }
+}
+
+// ---------------- 5. 导出 ----------------
+export const askUserQuestionTool: Tool<AskInput> = {
+  name: 'AskUserQuestion',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: true,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'cancel',
+  call,
+};

package/src/tools/bash/attachImage.js

@@ -0,0 +1,223 @@
+/**
+ * ============================================================
+ *  src/tools/bash/attachImage.ts —— Bash 的「让模型看一眼这张图」协议
+ * ------------------------------------------------------------
+ *  背景（为什么需要这个口子）：
+ *    Read 工具明确拒绝二进制/图片（read.ts 的黑名单），Bash 只能回文本，
+ *    全仓库唯一会产 `ToolResult.visionImages` 的是 WebBrowser。于是任何
+ *    「skill 脚本生成/截取了一张图，想让模型亲眼看看」的场景都物理上做不到 ——
+ *    computer-use（截屏）、生图核验、图表渲染核验全卡在这一处。
+ *
+ *  方案：约定一个 stdout sentinel。脚本自己打一行
+ *      <<<ATTACH_IMAGE:/abs/path.png|detail=low|maxLongSide=960>>>
+ *    Bash 解析出来填进 visionImages，并把该行**从给模型看的 content 里剥掉**
+ *    （协议是给宿主看的，不是给模型读的噪声）。
+ *
+ *  为什么是 Bash 的 sentinel 而不是新工具：
+ *    工具 schema 已占稳定系统提示词前缀的绝大头，新增一个多 action 的工具
+ *    等于让**所有用户的每次请求**都为它付 token。sentinel 是零新增 schema
+ *    字节的加性改动，而且天然通用 —— 任何脚本都能用，不绑任何具体 skill。
+ *
+ *  安全边界（重要）：
+ *    `multimodal.ts::imageToContentPart` 对路径**没有任何沙箱**，它会老实读
+ *    任何给它的绝对路径并 base64 进请求体。既然现在允许「命令输出决定读哪个
+ *    文件」，防线就必须建在这里：
+ *      ① 路径必须落在 cwd 或系统临时目录之下（realpath 之后比较，防软链逃逸）
+ *      ② 数量上限（图很贵，一次回 20 张能直接打爆上下文）
+ *      ③ 单图与总字节上限
+ *    越界的一律拒绝，并**如实写进 content 告诉模型哪张被拒、为什么** ——
+ *    静默丢弃会让脚本作者以为图发出去了，debug 时无从下手。
+ * ============================================================
+ */
+import { open, realpath, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { pathContains } from '../../utils/pathContains.js';
+import { MAX_IMAGE_BYTES, sniffImageMime } from '../../multimodal.js';
+/** 一次 Bash 调用最多附多少张图。图是上下文里最贵的东西，宁少勿多。 */
+export const MAX_ATTACH_IMAGES = 4;
+/**
+ * 一次 Bash 调用附图的总字节上限。取单图上限的 2 倍而非 4 倍：
+ * base64 会把体积撑到约 4/3，且 provider 侧有请求体上限（Claude 32MB），
+ * 留足余量给同一请求里的文本与历史。
+ */
+export const MAX_ATTACH_TOTAL_BYTES = MAX_IMAGE_BYTES * 2;
+/** 整行 sentinel（必须独占一行；行首尾允许空白）。 */
+const SENTINEL_LINE = /^[ \t]*<<<ATTACH_IMAGE:(.*?)>>>[ \t]*$/;
+/** 已知的可选段，从 payload 尾部往前剥；剩下的（可能含 `|`）才是路径。 */
+const OPTION_SEGMENT = /^(detail|maxLongSide)=(.*)$/;
+const VALID_DETAILS = new Set(['low', 'default', 'high']);
+/**
+ * 纯函数：从 stdout 里摘出 sentinel 行并剥除。不碰文件系统，便于单测。
+ *
+ * 无法识别的 payload（如空路径、只有选项没有路径）当作**普通输出行保留** ——
+ * 宁可让模型看到一行奇怪的文本，也不要把用户真实的输出悄悄吃掉。
+ */
+export function extractAttachImageDirectives(stdout) {
+    if (!stdout.includes('<<<ATTACH_IMAGE:')) {
+        return { text: stdout, directives: [] };
+    }
+    const directives = [];
+    const kept = [];
+    for (const line of stdout.split('\n')) {
+        const match = SENTINEL_LINE.exec(line);
+        if (!match) {
+            kept.push(line);
+            continue;
+        }
+        const directive = parsePayload(match[1] ?? '');
+        if (!directive) {
+            kept.push(line); // 认不出来的形状原样保留，不静默吞
+            continue;
+        }
+        directives.push(directive);
+    }
+    return { text: kept.join('\n'), directives };
+}
+/** 从尾部剥已知选项段，剩余部分（重新用 `|` 拼回）是路径 —— 容忍路径里含 `|`。 */
+function parsePayload(payload) {
+    const segments = payload.split('|');
+    let detail;
+    let maxLongSidePixel;
+    while (segments.length > 1) {
+        const tail = segments[segments.length - 1];
+        const option = OPTION_SEGMENT.exec(tail.trim());
+        if (!option)
+            break;
+        const [, key, rawValue] = option;
+        const value = (rawValue ?? '').trim();
+        if (key === 'detail') {
+            if (!VALID_DETAILS.has(value))
+                return null; // 写错了就整条不认，别猜
+            detail = value;
+        }
+        else {
+            const n = Number(value);
+            if (!Number.isFinite(n) || n <= 0)
+                return null;
+            maxLongSidePixel = Math.floor(n);
+        }
+        segments.pop();
+    }
+    const rawPath = segments.join('|').trim();
+    if (!rawPath)
+        return null;
+    return {
+        rawPath,
+        ...(detail ? { detail } : {}),
+        ...(maxLongSidePixel !== undefined ? { maxLongSidePixel } : {}),
+    };
+}
+/**
+ * 校验并解析成 `ImageInputSpec`。逐条独立判定 —— 一张被拒不影响其它张。
+ */
+export async function resolveAttachImages(directives, options = {}) {
+    if (directives.length === 0)
+        return { images: [], rejections: [] };
+    const maxImages = options.maxImages ?? MAX_ATTACH_IMAGES;
+    const maxTotalBytes = options.maxTotalBytes ?? MAX_ATTACH_TOTAL_BYTES;
+    const roots = await canonicalRoots(options.allowedRoots ?? [getWorkingDir(), tmpdir()]);
+    const images = [];
+    const rejections = [];
+    let totalBytes = 0;
+    for (const directive of directives) {
+        if (images.length >= maxImages) {
+            rejections.push(`${directive.rawPath}：一次最多附 ${maxImages} 张图，已超出`);
+            continue;
+        }
+        const absolute = resolve(getWorkingDir(), directive.rawPath);
+        const canonical = await canonicalize(absolute);
+        if (!roots.some((root) => isInside(root, canonical))) {
+            rejections.push(`${directive.rawPath}：路径不在当前工作目录或系统临时目录之下，已拒绝`);
+            continue;
+        }
+        const st = await stat(canonical).catch(() => null);
+        if (!st) {
+            rejections.push(`${directive.rawPath}：文件不存在或不可读`);
+            continue;
+        }
+        if (!st.isFile()) {
+            rejections.push(`${directive.rawPath}：不是普通文件`);
+            continue;
+        }
+        if (st.size > MAX_IMAGE_BYTES) {
+            rejections.push(`${directive.rawPath}：单图 ${(st.size / 1024 / 1024).toFixed(1)}MB 超过 ${MAX_IMAGE_BYTES / 1024 / 1024}MB 上限`);
+            continue;
+        }
+        if (totalBytes + st.size > maxTotalBytes) {
+            rejections.push(`${directive.rawPath}：累计体积超过 ${maxTotalBytes / 1024 / 1024}MB 上限，已跳过`);
+            continue;
+        }
+        const mime = await sniffFileImageMime(canonical);
+        if (!mime) {
+            rejections.push(`${directive.rawPath}：文件内容不是受支持的 JPEG/PNG/GIF/WEBP 图片，已跳过`);
+            continue;
+        }
+        totalBytes += st.size;
+        images.push({
+            source: canonical,
+            ...(directive.detail ? { detail: directive.detail } : {}),
+            ...(directive.maxLongSidePixel !== undefined
+                ? { maxLongSidePixel: directive.maxLongSidePixel }
+                : {}),
+        });
+    }
+    return { images, rejections };
+}
+/**
+ * 在接受 sentinel 时验魔数，不依赖扩展名。只读取头部，避免为拒绝一张大文件
+ * 再做一次完整读取。逐条返回 null，由调用方记录 rejection，不抛到整个回合。
+ */
+async function sniffFileImageMime(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const header = Buffer.alloc(16);
+        const { bytesRead } = await handle.read(header, 0, header.length, 0);
+        return sniffImageMime(header.subarray(0, bytesRead));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+/**
+ * realpath 之后再比较 —— 否则一条指向 /etc 的软链就能绕过根目录白名单。
+ *
+ * 目标不存在时不能简单退回 `resolve()`：macOS 的 `os.tmpdir()` 是
+ * `/var/folders/…`（软链到 `/private/var/folders/…`），根目录已归一化而目标没有，
+ * 于是「临时目录下一个还没生成的文件」会被判成**越界**而不是**不存在** ——
+ * 报错指向错误的原因，脚本作者会去查权限而不是去查文件名。
+ * 因此回退到「归一化最近的存在祖先，再接回剩余段」。
+ */
+async function canonicalize(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        if (parent === absolute)
+            return absolute; // 已到根，停止递归
+        return join(await canonicalize(parent), basename(absolute));
+    }
+}
+/**
+ * 根目录也必须 realpath：macOS 的 `os.tmpdir()` 返回 `/var/folders/...`，
+ * 而它其实是 `/private/var/folders/...` 的软链 —— 不归一化的话临时目录里的
+ * 图会被自己的边界检查误杀。
+ */
+async function canonicalRoots(roots) {
+    const out = [];
+    for (const root of roots) {
+        const canonical = await canonicalize(resolve(root));
+        if (!out.includes(canonical))
+            out.push(canonical);
+    }
+    return out;
+}
+/** target 是否落在 root 之内（含 root 自身）。判据实现见 `utils/pathContains.ts`（全仓唯一一份）。 */
+const isInside = pathContains;