minimal-agent 0.13.0 → 0.14.0

package/workflows/research/prompts/s6-package.md

@@ -0,0 +1,32 @@
+你在执行最后的「精选交付」步骤：把值得交付的验证脚本从 `{{dir}}/verify/` 精选、
+清理后复制进 `{{dir}}/deliverable/scripts/`。
+
+`{{dir}}/verify/` 里的失败/废弃/探索性脚本是**过程记录，一律不进入交付目录**。
+
+请先 Read：
+- `{{dir}}/05-verification.md`（哪些脚本验证通过、对应什么结论）
+- `{{dir}}/06-synthesis.md` 的「三b、已通过脚本验证的关键结论」小节（哪些结论被最终引用）
+- Glob `{{dir}}/verify/*`（现有脚本清单）
+
+## 筛选规则（**三条同时满足**才复制）
+1. 该脚本对应的验证记录是「验证通过」；
+2. 对应结论被 06-synthesis.md 引用了；
+3. 脚本能独立用 `bun run` / `node` 运行。
+
+## 复制时做最小整理
+- 去掉纯调试用的打印；
+- 文件头补 2-3 行注释：这个脚本验证什么结论、怎么运行、预期输出；
+- 文件名要能看出验证内容（如 `verify_binance_kline_fetch.ts`，不要 `test3_v2.ts`）。
+
+## 必须写 `{{dir}}/deliverable/scripts/README.md`（脚本清单表）
+
+| 脚本文件名 | 对应结论（简述） | 运行方式 | 预期输出说明 |
+|---|---|---|---|
+
+交付目录里每个脚本都必须在表里有一行。
+若没有可交付脚本（提前退出路径 / 全部验证失败 / 全部待人工验证），
+README 直接写明原因（例：「本次调研提前退出，未产生验证脚本」），**不要硬凑**。
+
+## 约束
+- 只准往 `{{dir}}/deliverable/scripts/` 写，**不改 `{{dir}}/verify/` 里的原件**。
+- 不确定某脚本是否该交付时，**宁可不交付**、在 README 里说明。

package/workflows/research/scripts/build-report.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * workflows/research/scripts/build-report.mjs —— 把各阶段产物拼装成最终报告
+ *
+ * 用法：node workflows/research/scripts/build-report.mjs <研究目录> <depth>
+ *
+ * 自 research.yaml 的 s6_build_report 迁移。原来是一大段 bash：
+ *   sec() { sed -E 's/^(#+) /\1## /' "$1"; }
+ * 改写成 node 的三个理由（不是为了好看）：
+ *  ① **可移植**：原版依赖 `sed -E`、`set -euo pipefail`、`basename`，Windows 上要靠
+ *     Git Bash 才有；宿主回落 cmd 时整段直接不可用（本项目为此踩过坑）。
+ *  ② **可单独跑**：拼装出问题时 `node scripts/build-report.mjs out/research/x standard`
+ *     一条命令复现，不用启动整条工作流等前面五个阶段跑完。
+ *  ③ **注入面为零**：原版把 depth 内插进 shell 命令体（虽是 enum 白名单所以当时安全），
+ *     这里根本不经过 shell。
+ *
+ * 标题降级的取舍与原版一致：子文档的 `#` 降两级成 `###`，落在章节 `##` 之下。
+ * 已知副作用：代码块里顶格的 `# 注释` 也会被降级 —— 纯视觉影响，不改语义。
+ */
+
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const [dir, depth = 'standard'] = process.argv.slice(2);
+if (!dir) {
+  console.error('用法：build-report.mjs <研究目录> [depth]');
+  process.exit(1);
+}
+
+/** 读文件并把所有标题降两级；文件不存在返回占位说明而不是空串。 */
+function section(file) {
+  if (!existsSync(file)) {
+    return `> ⚠️ 缺少 \`${basename(file)}\` —— 该阶段可能被跳过或失败，详见 progress.md。`;
+  }
+  return readFileSync(file, 'utf8').replace(/^(#+) /gm, '$1## ');
+}
+
+const out = [];
+const push = (...lines) => out.push(...lines);
+const rule = () => push('', '---', '');
+
+push('# 技术研究报告', '');
+push(`_调研深度：${depth}　|　由 minimal-agent research 工作流自动生成_`);
+rule();
+
+push('## 1. 目标与边界', '');
+push(section(join(dir, '01-goal.md')));
+rule();
+
+push('## 2. 领域地图', '');
+push(section(join(dir, '02-map.md')));
+rule();
+
+push('## 3. 候选方案对比', '');
+push(section(join(dir, '03-options.md')));
+rule();
+
+push('## 4. 深度调研', '');
+let dives = [];
+try {
+  dives = readdirSync(dir)
+    .filter((f) => f.startsWith('04-deep-dive-') && f.endsWith('.md'))
+    .sort();
+} catch {
+  /* 目录读不到就当没有深挖文件 */
+}
+if (dives.length === 0) {
+  push('> 本次调研未产生深度调研分支（可能走了提前退出路径）。', '');
+} else {
+  for (const f of dives) {
+    push(`### ${f.replace(/^04-deep-dive-/, '').replace(/\.md$/, '')}`, '');
+    push(section(join(dir, f)), '');
+  }
+}
+rule();
+
+push('## 5. 动手验证', '');
+push(section(join(dir, '05-verification.md')));
+rule();
+
+push('## 6. 综合结论与建议', '');
+push(section(join(dir, '06-synthesis.md')));
+
+if (existsSync(join(dir, '07-learning-debt.md'))) {
+  rule();
+  push('## 7. 学习债务与后续研究方向', '');
+  push(section(join(dir, '07-learning-debt.md')));
+}
+
+rule();
+push('_本报告由 minimal-agent research 工作流自动生成。验证脚本见 deliverable/scripts/ 及其 README。_');
+
+const target = join(dir, 'deliverable', 'report.md');
+mkdirSync(join(dir, 'deliverable', 'scripts'), { recursive: true });
+writeFileSync(target, `${out.join('\n')}\n`, 'utf8');
+
+// 输出给调用方解析：路径 + 拼进去了几个深挖分支
+console.log(JSON.stringify({ ok: true, path: target, dives: dives.length }));

package/workflows/research/workflow.mjs

@@ -0,0 +1,288 @@
+export const meta = {
+  apiVersion: 2,
+  description:
+    '六阶段技术深度调研：定义问题→测绘领域地图→候选方案对比→分支深度调研→动手验证→综合升华。产出含知识地图、对比矩阵、验证记录与最终建议的报告',
+  inputs: [
+    {
+      name: 'topic',
+      required: true,
+      greedy: true,
+      description: '要调研的技术主题/问题/领域（自然语言一句话，越具体越好）',
+    },
+    {
+      name: 'depth',
+      type: 'enum',
+      values: ['light', 'standard', 'deep'],
+      default: 'standard',
+      description: '调研深度（light=快速扫盲；standard=可用结论；deep=学术级深度）',
+    },
+    {
+      name: 'max_iterations',
+      type: 'number',
+      default: 2,
+      description: '综合阶段自检-补洞最大轮数（防无限递归）',
+    },
+  ],
+  artifacts: [],
+}
+
+export default async function run(wf) {
+const { values: args } = wf.input
+const { sessionId: session, taskId: task, workflowDir } = wf.runtime
+const { agent } = wf.model
+const { shell: sh, file: execFile } = wf.exec
+const { readText, readJson, exists } = wf.fs
+const { ask } = wf.flow
+const { budget, resetModelContext: resetContext, addGoalSupplement } = wf.state
+const echo = wf.output.message
+const declareArtifact = wf.output.artifact
+const log = (message) => wf.output.progress({ phase: 'workflow', status: 'update', message: String(message) })
+
+// ============================================================
+//  自 research.yaml 迁移。本文件是**流程的目录** —— 细节下沉到：
+//    prompts/*.md          九段长 prompt（改措辞不用动代码，diff 干净）
+//    scripts/build-report.mjs  报告拼装（原 bash 用 sed/basename，Windows 上不可靠）
+//
+//  六阶段 + 两个可选分支：
+//    阶段0 定义问题 →（用户确认闸门）
+//    阶段1 测绘地图 →【提前退出判定】→ 是：简化报告直奔阶段6
+//    阶段2 方案对比 → 阶段3 逐分支深挖 → 阶段4 动手验证 → 阶段5 综合
+//    阶段5b 自检补洞循环（缺口清空即退出）
+//    阶段6 确定性拼装报告 + 精选脚本交付
+// ============================================================
+
+const DIR = `out/research/${session}/${task}`
+const REPORT = `${DIR}/deliverable/report.md`
+const PROMPTS = typeof workflowDir === 'string' && workflowDir ? `${workflowDir}/prompts` : 'workflows/research/prompts'
+
+/** 读 prompt 文件并填占位符。用 readText 而不是 tool('Read')：后者返回的是
+ *  给模型看的格式（每行带「行号+TAB」前缀），整段行号会跟着进 prompt。 */
+async function prompt(name, vars = {}) {
+  const raw = await readText(`${PROMPTS}/${name}.md`)
+  if (raw === null) throw new Error(`读不到 prompt 文件：${PROMPTS}/${name}.md`)
+  let text = raw
+  for (const [k, v] of Object.entries({ topic: args.topic, depth: args.depth, dir: DIR, ...vars })) {
+    text = text.split(`{{${k}}}`).join(String(v ?? ''))
+  }
+  return text
+}
+
+/**
+ * 跑一个阶段并核实它该产出的文件；没产出就有界 nudge。
+ * 这是脊梁规则的统一实现 —— 每个写文件的阶段都必须经它，不许直接 agent()。
+ */
+async function stage(label, promptText, outputs, opts = {}) {
+  let out = await agent(promptText, { label, maxTurns: opts.maxTurns ?? 25, ...opts })
+  for (let i = 1; i <= 2; i++) {
+    const missing = []
+    for (const f of outputs) if (!(await exists(f))) missing.push(f)
+    if (missing.length === 0) break
+    log(`${label}：还缺 ${missing.length} 个文件，第 ${i} 次提醒`)
+    out = await agent(
+      `以下文件还没有生成：\n${missing.map((m) => `- ${m}`).join('\n')}\n\n` +
+        '请**现在就调用 Write 工具**把它们写出来，不要只描述你打算做什么。内容要求见上一条消息。',
+      { label: `${label}·nudge-${i}`, allowedTools: opts.allowedTools, maxTurns: 12 },
+    )
+  }
+  const still = []
+  for (const f of outputs) if (!(await exists(f))) still.push(f)
+  if (still.length > 0) {
+    throw new Error(`${label} 未能产出：${still.join('、')}`)
+  }
+  for (const f of outputs) declareArtifact(f)
+  return out
+}
+
+const RESEARCH_TOOLS = ['WebSearch', 'WebFetch', 'Read', 'Write', 'Bash', 'Glob']
+
+// ── 初始化：只 mkdir，不删任何文件 ──────────────────────────────────
+// 产物路径唯一且命名固定，子 agent 用 Write 覆盖本身就幂等；用 rm 反而会
+// 静默删掉用户预先放在这里的东西，也会撞上 Bash 的永久删除守卫。
+await sh(`mkdir -p ${DIR}/verify ${DIR}/deliverable/scripts`)
+
+// ── 阶段 0：定义问题 ────────────────────────────────────────────────
+await stage('阶段0/6·定义问题', await prompt('s0-goal'), [`${DIR}/01-goal.md`], {
+  allowedTools: ['Read', 'Write'],
+  maxTurns: 12,
+})
+// 澄清结论并入贯穿目标，后续每一步（含打回重来轮）都看得到
+await addGoalSupplement(`调研目标定义见 ${DIR}/01-goal.md`)
+
+// ── 用户确认闸门（非交互宿主自动选推荐项，不挂起）────────────────────
+const approval = await ask(
+  `已完成问题定义，请阅读 ${DIR}/01-goal.md。\n` +
+    '确认核心问题、范围边界、验收标准是否符合预期；要调整范围或补充要求就选「其他」输入，' +
+    '工作流会把它作为补充要求贯穿全程。',
+  [
+    { label: '继续执行 (推荐)', description: '按当前问题定义继续调研' },
+    { label: '停止', description: '中止本次运行；现场保留可续跑' },
+  ],
+)
+if (approval.includes('停止')) {
+  throw new Error('用户在问题定义确认闸门选择停止（现场已保留，重跑同目标可续跑）')
+}
+if (!approval.includes('继续执行') && approval.trim()) {
+  await addGoalSupplement(approval)
+  log('已把你的补充要求并入贯穿目标')
+}
+
+// ── 阶段 1：测绘领域地图 + 提前退出判定 ─────────────────────────────
+await stage(
+  '阶段1/6·测绘领域地图',
+  await prompt('s1-map'),
+  [`${DIR}/02-map.md`, `${DIR}/early-exit.json`],
+  { allowedTools: RESEARCH_TOOLS, maxTurns: 25 },
+)
+
+const exitJson = await readJson(`${DIR}/early-exit.json`)
+const earlyExit = exitJson?.early === true
+if (earlyExit) {
+  log(`提前退出：${exitJson?.reason ?? '（未给理由）'}`)
+}
+
+if (earlyExit) {
+  // ── 简化路径：一次补齐全套文件，让阶段6 的拼装无需分叉 ──────────────
+  await stage(
+    '简化路径·补齐全套文件',
+    await prompt('s1-early-exit'),
+    [
+      `${DIR}/03-options.md`,
+      `${DIR}/branches.json`,
+      `${DIR}/05-verification.md`,
+      `${DIR}/06-synthesis.md`,
+      `${DIR}/07-learning-debt.md`,
+      `${DIR}/gaps.json`,
+    ],
+    { allowedTools: ['Read', 'Write'], maxTurns: 12 },
+  )
+} else {
+  // ── 阶段 2：候选方案对比 ──────────────────────────────────────────
+  await stage(
+    '阶段2/6·候选方案对比',
+    await prompt('s2-options'),
+    [`${DIR}/03-options.md`, `${DIR}/branches.json`],
+    { allowedTools: RESEARCH_TOOLS, maxTurns: 25 },
+  )
+
+  const branches = await readJson(`${DIR}/branches.json`)
+  if (!Array.isArray(branches) || branches.length === 0) {
+    throw new Error(
+      `未能从 ${DIR}/branches.json 读到任何深度调研分支（JSON 格式错误或数组为空）`,
+    )
+  }
+
+  // ── 阶段 3：逐分支深挖。每轮重置上下文，分支之间互不干扰 ────────────
+  for (const [i, branch] of branches.entries()) {
+    resetContext()
+    const safe = String(branch.safe_name ?? `branch-${i + 1}`).replace(/[^\w.-]/g, '-')
+    await stage(
+      `阶段3/6·深挖「${branch.name ?? safe}」`,
+      await prompt('s3-deep-dive', {
+        branchName: branch.name ?? safe,
+        branchDesc: branch.description ?? '（未给描述，按分支名自行判断）',
+        safeName: safe,
+      }),
+      [`${DIR}/04-deep-dive-${safe}.md`],
+      { allowedTools: RESEARCH_TOOLS, maxTurns: 30 },
+    )
+  }
+
+  // ── 阶段 4：动手验证 ─────────────────────────────────────────────
+  resetContext()
+  await stage('阶段4/6·动手验证', await prompt('s4-verify'), [`${DIR}/05-verification.md`], {
+    allowedTools: ['Bash', 'Read', 'Write', 'Glob', 'WebSearch', 'WebFetch'],
+    maxTurns: 25,
+  })
+
+  // ── 阶段 5：综合升华 ─────────────────────────────────────────────
+  resetContext()
+  await stage(
+    '阶段5/6·综合结论',
+    await prompt('s5-synthesis'),
+    [`${DIR}/06-synthesis.md`, `${DIR}/07-learning-debt.md`, `${DIR}/gaps.json`],
+    { allowedTools: ['Read', 'Write', 'Glob', 'WebSearch', 'WebFetch'], maxTurns: 20 },
+  )
+
+  // ── 阶段 5b：自检补洞循环，缺口清空即退出 ──────────────────────────
+  const maxRounds = Number(args.max_iterations ?? 2)
+  for (let round = 1; round <= maxRounds; round++) {
+    // 预算闸只在开新一轮之前判 —— 补洞循环是本工作流里唯一「不断开新一轮」的地方，
+    // 前面那些 for 都是按数据项遍历（有界，不会失控），不需要也不该加。
+    const money = await budget()
+    if (money.exhausted) {
+      echo(`\n💰 token 预算已用尽（已花 ${money.used} / 上限 ${money.limit}），补洞循环停在第 ${round - 1} 轮。`)
+      echo('已产出的部分完好；加大预算后重跑可从断点继续。')
+      break
+    }
+    const gaps = await readJson(`${DIR}/gaps.json`)
+    if (!Array.isArray(gaps) || gaps.length === 0) {
+      echo('✅ 自检无缺口，补洞循环结束。')
+      break
+    }
+    resetContext()
+    log(`补洞第 ${round}/${maxRounds} 轮，待补 ${gaps.length} 条`)
+    await agent(
+      await prompt('s5b-fill-gaps', {
+        round: String(round),
+        gaps: gaps.map((g) => `- ${g}`).join('\n'),
+      }),
+      {
+        label: `阶段5b·补洞第 ${round}/${maxRounds} 轮`,
+        allowedTools: RESEARCH_TOOLS,
+        maxTurns: 20,
+      },
+    )
+  }
+}
+
+// ── 综合报告形式校验：确定性，不依赖 agent 自觉 ─────────────────────
+// 「核心结论」兼容两种表述：prompt 要求的字面 + agent 改写时常见的
+// 「核心问题的一句话答案」（实战中补洞轮曾改写标题导致误判 halt）。
+const synth = await sh(
+  `grep -E '^#+ .*(核心结论|核心问题的一句话答案|推荐方案)' ${DIR}/06-synthesis.md || true`,
+)
+const hasConclusion = /核心结论|一句话答案/.test(synth.stdout)
+const hasRecommend = synth.stdout.includes('推荐方案')
+if (!hasConclusion || !hasRecommend) {
+  throw new Error(
+    `${DIR}/06-synthesis.md 缺少「核心结论」或「推荐方案」章节 —— ` +
+      '综合报告没有直接回答核心问题，不允许进入拼装。',
+  )
+}
+
+// ── 阶段 6：确定性拼装最终报告 ──────────────────────────────────────
+const built = await execFile('./scripts/build-report.mjs', [DIR, String(args.depth ?? 'standard')])
+if (built.exitCode !== 0) {
+  throw new Error(`报告拼装失败：${built.stderr || built.stdout}`)
+}
+if (!(await exists(REPORT))) {
+  throw new Error(`报告拼装脚本报告成功，但 ${REPORT} 不存在`)
+}
+declareArtifact(REPORT)
+
+// ── 阶段 6：精选验证脚本交付（失败不阻断，报告已经在手）──────────────
+try {
+  await stage(
+    '阶段6/6·精选脚本交付',
+    await prompt('s6-package'),
+    [`${DIR}/deliverable/scripts/README.md`],
+    { allowedTools: ['Read', 'Write', 'Bash', 'Glob'], maxTurns: 12 },
+  )
+} catch (e) {
+  log(`精选交付降级（不阻断，报告已生成）：${e.message}`)
+}
+
+// ── 收尾 ───────────────────────────────────────────────────────────
+const remaining = await readJson(`${DIR}/gaps.json`)
+const gapCount = Array.isArray(remaining) ? remaining.length : 0
+
+echo(`✅ 技术调研完成\n\n主题：${args.topic}\n深度：${args.depth ?? 'standard'}`)
+echo(
+  gapCount > 0
+    ? `⚠️ 补洞循环达上限退出，仍有 ${gapCount} 条缺口未补全（见 ${DIR}/gaps.json 与 06-synthesis.md 的「调研局限」），结论使用时注意置信度。`
+    : '✅ 调研缺口已全部收敛。',
+)
+echo(`★ 请直接阅读汇总报告：${REPORT}\n  过程产物在 ${DIR}/，精选脚本在 ${DIR}/deliverable/scripts/`)
+
+return { report: REPORT, dir: DIR, remainingGaps: gapCount, earlyExit }
+}

package/workflows/wechat-reading-shots/prompts/collect-params.md

@@ -0,0 +1,16 @@
+本次任务需要三个参数。**已经给了的直接用，只问缺的那些**：
+
+    书名     book       = 「{{book}}」   （空字符串 = 未提供）
+    起始页   start_page = {{startPage}}  （0 = 未提供）
+    截图张数 shots      = {{shots}}      （0 = 未提供）
+
+有缺失就用 **AskUserQuestion 一次性问清所有缺的项**（不要一项一项分多轮问）。
+给选项的同时也允许自由输入：起始页给 1 / 12 / 50 之类，张数给 5 / 10 / 20 之类。
+
+三项都齐了就**不要问任何问题**，直接输出结果。
+
+最后**只回复一行 JSON**，不要任何解释、不要代码块围栏：
+
+```
+{"book":"书名","page":起始页数字,"shots":张数数字}
+```

package/workflows/wechat-reading-shots/prompts/evaluate.md

@@ -0,0 +1,20 @@
+评估**这次自动化跑得成不成功**（不是评估书的内容）。
+
+本次流程：打开《{{book}}》正文 → 翻到第 {{targetPage}} 页（落点 {{landing}}）→
+循环 {{shots}} 次「截图 + 翻页」，实际拍了 {{actualShots}} 张。
+
+observe 一次（用说明书的 `read_page_number` 流程读清当前页码），结合过程中看到的
+截图，如实回答：
+
+1. 打开的确实是《{{book}}》吗？依据是什么？
+2. 截图是否都是**不同**的页面？依据是每次翻页回执里的变化率（0.0% = 没翻动）。
+3. 过程中有没有误触？（弹出菜单、放大插图、跳转别的界面、触发购买/分享）
+4. 当前停在第几页？用放大镜读出来的真实数字，不要猜。
+
+要求：
+
+- 每条结论都要说清依据，不要笼统说"成功"
+- 拿不准就明说拿不准
+- **不要凭记忆报按键次数或截图张数** —— 那两个数字上面已经给你了，
+  它们由引擎的循环结构保证，比你的记忆可靠
+- 最后一句总评：成功 / 部分成功 / 失败，以及卡在哪一步

package/workflows/wechat-reading-shots/prompts/open-book.md

@@ -0,0 +1,28 @@
+把微信读书弄到《{{book}}》的**正文页**。
+
+判据只有一条：**能读出页码**（形如「N / 总数」）。读得到就算完成。
+读页码的方法、界面各处的位置、遇到奇怪界面怎么退回去 —— 说明书里都有，
+它的摘要就在你每次 observe 的回执里，照着做。
+
+⛔ **这一步只负责「打开到正文页」，到此为止。**
+**不要**去翻到第几页 —— 说明书里那条 seek_to_page 流程不归你执行，
+下一步由引擎驱动，它会先读页码再决定翻多少。你在这里翻页只会把落点搞乱。
+**一旦读到页码，立刻回 OPEN=ok 结束本步**，一个多余动作都不要做。
+（实测教训：这一步曾自作主张把书翻到目标页，干了 4 分钟、还忘了给结论行，
+整条工作流因为「没有产出任何结果」而 halt。）
+
+纪律：
+
+- 第一个动作必须是 observe，先看清在哪再决定做什么
+- 只读任务：不点购买 / 订阅 / 分享 / 赠一得一 / 加入书架
+- **搜索结果里出现多本书名高度相似的书时（这在本应用里非常常见），
+  不要自己挑 —— 用 AskUserQuestion 把候选的完整书名 + 作者列给用户确认。**
+  点错书的代价是后面全部十几张截图都白拍。
+- 操作飞到了不认识的界面：按说明书的 back_to_home 流程复位。
+  **别在原地反复试**，也别用鼠标去正文里乱点。
+- 其它卡住、拿不准的地方一样用 AskUserQuestion 问，不要瞎试
+
+⚠️ 无论过程如何，**最后一行必须是下面两者之一**，缺了这行整步算失败：
+
+- 已停在能读到页码的正文页 → `OPEN=ok`
+- 试过各种办法仍进不去     → `OPEN=fail`

package/workflows/wechat-reading-shots/prompts/read-page.md

@@ -0,0 +1,13 @@
+只做一件事：**读出当前页码**。不要翻页，不要点任何东西。
+
+方法见说明书的 `read_page_number` 流程（摘要就在你每次 observe 的回执里）。
+
+**只回复一行**，格式严格如下，不要任何解释：
+
+```
+PAGE=<左页码> <右页码>
+```
+
+例：`PAGE=84 85`；单页显示时两个写一样：`PAGE=12 12`。
+
+实在读不出来就回复：`PAGE=0 0`

package/workflows/wechat-reading-shots/prompts/turn-batch.md

@@ -0,0 +1,24 @@
+当前页码：{{curPage}}   目标页：{{targetPage}}
+
+照这三步做，**不要自由发挥**：
+
+① 取当前左页码 L —— 就是 `{{curPage}}` 里的第一个数字
+
+② 方向 = L > {{targetPage}} 时用 `left`，否则用 `right`
+   N（还要按几次）= 向上取整( |L − {{targetPage}}| ÷ 2 )
+   （每次按键翻几页由说明书 `seek_to_page` 给出，别自己假设）
+
+③ 按 N 发**一次**工具调用，然后立刻结束本步：
+   - N ≥ 5 → `{action:"key", key:"<方向>", repeat:<min(N,8)>, repeatFrames:"last"}`
+   - N ≤ 4 → `{action:"key", key:"<方向>"}`
+
+⛔ **N ≥ 5 时必须用 repeat 一次发满，不许一下一下按。**
+   一下一下按，每按一次都要多花一个完整的 LLM 往返（约 30 秒），
+   而 repeat 一轮就干完（约 1 秒）—— 实测 N=6 时一次一按比批量多花了 5 分钟。
+   `repeatFrames:"last"` 也必须带上：不带的话 `repeat:8` 会回 8 张全屏图
+   （约 1 万 token），而中间那些页你根本不看。
+
+⛔ 发完就结束本步。不要自己循环、不要自己再 observe 确认 ——
+   外层引擎下一轮会先重新读页码，那才是权威值。
+
+⛔ 全程零鼠标。