weaver-work-cli 0.1.28 → 0.1.31

package/skills/weaver-e10-workflow/scripts/todo-summary.cjs

@@ -0,0 +1,695 @@
+#!/usr/bin/env node
+/**
+ * 待办智能汇总 —— 固定流水线脚本（供 weaver-e10-workflow skill 使用）
+ *
+ * 一句话：把「取数 → 过滤 → (模型分组) → 组装 → (模型写摘要) → 导出校验」固化成三段命令，
+ * 避免每次现场拼脚本，也避免多跑一次 stage=group 进程（每次 CLI 启动约 6~7s）。
+ *
+ * 用法：
+ *   node todo-summary.cjs prep   --limit 100 [--exclude 内部留言] [--days 365] [--out DIR]
+ *       → 取数、按 workflowName 剔除指定流程、打印分组素材（模型据此做二次分组）
+ *   node todo-summary.cjs build  --dir DIR --plan aiGroups.json
+ *       → 校验 1..count 全覆盖 → smartGroup；若还有待写摘要则打印，否则直接导出终态
+ *   node todo-summary.cjs finish --dir DIR [--summaries aiSummaries.json]
+ *       → 回填摘要（可选）→ 导出终态 JSON → 打印结构自检与耗时
+ *
+ * 铁律：二次分组每轮都必须由模型现场产出 aiGroups，本脚本只做校验与组装，不做任何复用/缓存。
+ */
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CLI = process.env.WEAVER_CLI || 'weaver-work-cli';
+
+/**
+ * 宿主（WorkBuddy）会给每个 node 子进程注入
+ * `NODE_OPTIONS=--require=.../node-language-shim.cjs`，该 shim 对**每次 fs 读取**加约 10~16ms 审计：
+ * 本 CLI 启动要读 387 个模块 ⇒ 每次进程 ~3.9s，3 个阶段就是 12s+（实测 22~28s 的异常也来自它）。
+ *
+ * 这里启动 CLI 时只摘掉 shim 这一项，其它 NODE_OPTIONS 原样保留。
+ * 实测：`--version` 4.96s → 0.16s，`workflow schema` 7.23s → 0.19s（2026-10-27）。
+ * 需要保留 shim 时设 `WEAVER_WORK_CLI_KEEP_NODE_SHIM=1`。
+ */
+function cliEnv() {
+  const env = { ...process.env };
+  if (env.WEAVER_WORK_CLI_KEEP_NODE_SHIM) return env;
+  const raw = env.NODE_OPTIONS || '';
+  if (!raw.includes('node-language-shim')) return env;
+  const cleaned = raw
+    // `--require="…/node-language-shim.cjs"` 或 `--require …/node-language-shim.cjs` 两种写法
+    .replace(/--require\s*=?\s*("[^"]*node-language-shim\.cjs"|'[^']*node-language-shim\.cjs'|[^\s"']*node-language-shim\.cjs)/g, '')
+    .trim();
+  if (cleaned) env.NODE_OPTIONS = cleaned;
+  else delete env.NODE_OPTIONS;
+  return env;
+}
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith('--')) {
+      const key = token.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) out[key] = true;
+      else { out[key] = next; i += 1; }
+    } else out._.push(token);
+  }
+  return out;
+}
+
+function cli(args) {
+  const raw = execFileSync(CLI, ['--json', 'workflow', 'run', 'workflow.todoSmartConvert', ...args], {
+    encoding: 'utf8',
+    maxBuffer: 512 * 1024 * 1024,
+    env: cliEnv(),
+  });
+  const parsed = JSON.parse(raw);
+  if (!parsed.ok) {
+    const error = parsed.error || {};
+    console.error(`✖ ${error.subtype || error.type || 'error'}: ${error.message || JSON.stringify(parsed)}`);
+    process.exit(1);
+  }
+  return parsed;
+}
+
+function runStage(input, dir, name) {
+  const file = path.join(dir, `in-${name}.json`);
+  fs.writeFileSync(file, JSON.stringify(input));
+  return cli(['--input', file, '--allow-file-input']);
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function fmt(ms) {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** 从结果信封里取某个 stage 的 **CLI 内部**耗时（不含 node 启动）；取不到返回 null。 */
+function cliStageMs(result, stage) {
+  const steps = (result && result.meta && result.meta.timing && result.meta.timing.steps) || [];
+  const hit = steps.filter((step) => step && step.name === stage).pop();
+  return hit && Number.isFinite(hit.durationMs) ? hit.durationMs : null;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function groupStats(wfIdGroup) {
+  let covered = 0;
+  let singles = 0;
+  let empty = 0;
+  const rows = [];
+  for (const group of wfIdGroup) {
+    const items = group.displayItems || [];
+    const subs = items.filter((x) => x.type === 'group');
+    const one = items.filter((x) => x.type === 'request');
+    covered += subs.reduce((sum, x) => sum + x.count, 0);
+    singles += one.length;
+    for (const item of items) {
+      const summary = item.type === 'group' ? item.summary : item.requestData.summary;
+      if (!summary) empty += 1;
+    }
+    rows.push({
+      title: group.title,
+      count: group.count,
+      display: subs.map((x) => `${x.title}(${x.count})`).join('、') || '-',
+      singles: one.length,
+    });
+  }
+  return { covered, singles, empty, rows };
+}
+
+/**
+ * 导出最终结构。
+ *
+ * 交付形态（用户 2026-10-22 硬规则）：**只在对话里输出 JSON + 耗时，不产物理文件**。
+ * 所以默认走「stdout-only」：把最终结构的 JSON 打到 stdout 的 `[JSON_BEGIN]/[JSON_END]` 之间，
+ * 由 Agent 原样贴进回复；只有显式传 `--file` 才写成 `待办汇总-*.json`（兼容旧用法/调试）。
+ *
+ * 顶层键固定三个：`smartSummaryTitle` / `totalCount` / `wfIdGroup`（用户 2026-10-25 要求加
+ * `totalCount` = 当前这批数据的总条数，与各大分组 `count` 之和一致）。
+ */
+/**
+ * 生成本轮耗时说明（markdown 文本）。数据全部来自 `state.json`（各阶段墙钟 / CLI 内部耗时）
+ * 与最终结果，所以「落 JSON + 耗时摘要」可以**一次调用**完成，不必再单独跑一轮查询。
+ *
+ * 2026-10-27 起：文本**不再落盘成 md 交付物**，只在 `--timing-report` 时取「结论」段打到控制台；
+ * 同日起**请求级埋点已移除**（`requestTiming` 模块删除），只报「墙钟 vs CLI 内部」两个口径。
+ *
+ * 两个口径必须分开报，否则会误判瓶颈：
+ *  - 墙钟：含 node 启动 + 模块加载；
+ *  - CLI 内部：只含业务（请求 + 计算）。
+ */
+function buildTimingReport(state, result) {
+  const stages = [
+    { name: 'collect（取数）', wall: state.collectWallMs, inner: state.collectMs },
+    { name: 'smartGroup（分组）', wall: state.smartGroupWallMs, inner: state.smartGroupInternalMs },
+    { name: 'summary（摘要）', wall: state.summaryWallMs, inner: state.summaryInternalMs },
+    { name: 'groupSummary（组摘要回填）', wall: state.groupSummaryWallMs, inner: state.groupSummaryInternalMs },
+  ].filter((stage) => Number.isFinite(stage.wall) && stage.wall > 0);
+  const total = (pick) => stages.reduce((acc, stage) => acc + (Number(pick(stage)) || 0), 0);
+  const wallMs = total((stage) => stage.wall);
+  const innerMs = total((stage) => stage.inner);
+  const pct = (part) => (wallMs > 0 ? `${((part / wallMs) * 100).toFixed(0)}%` : '-');
+  const scope = state.days ? `近 ${state.days} 天`
+    : (state.from && state.to ? `${state.from} ~ ${state.to}` : `前 ${state.limit} 条`);
+  const data = result.data;
+  const lines = [];
+  lines.push('# 待办汇总耗时说明', '');
+  lines.push(`> 范围：${scope}｜${data.totalCount} 条待办 / ${data.wfIdGroup.length} 组`);
+  lines.push(`> 生成：${new Date().toISOString().slice(0, 19).replace('T', ' ')} UTC`);
+  lines.push('', '## 1. 结论', '');
+  lines.push(`- 总墙钟 **${fmt(wallMs)}**，其中**真实业务 ${fmt(innerMs)}（${pct(innerMs)}）**，进程启动与模块加载占 ${pct(wallMs - innerMs)}。`);
+  lines.push('- ⚠️ 本报告**只统计 CLI 执行链路**。端到端（用户看到的「已完成 X」）还要叠加模型往返——每步 20~35s，通常远大于这里的总墙钟。');
+  lines.push('', '## 2. 分阶段', '');
+  lines.push('| 阶段 | 墙钟 | CLI 内部 | 业务占比 |');
+  lines.push('|---|---|---|---|');
+  for (const stage of stages) {
+    lines.push(`| ${stage.name} | ${fmt(stage.wall)} | ${Number.isFinite(stage.inner) ? fmt(stage.inner) : '—'} | ${pct(stage.inner)} |`);
+  }
+  lines.push(`| **合计** | **${fmt(wallMs)}** | **${fmt(innerMs)}** | **${pct(innerMs)}** |`);
+  lines.push('', '## 3. 优化提示', '');
+  lines.push('- 若「业务占比」很低：瓶颈在**CLI 进程启动**。根因是宿主注入的 node shim 对每次 fs 读取加 ~10ms 审计（387 个模块 ≈ 4s/次）；本脚本已自动摘掉 shim，若这里仍看到 4s+，检查是否设了 `WEAVER_WORK_CLI_KEEP_NODE_SHIM=1`。');
+  lines.push('- 「待写摘要为 0」时脚本会直接导出，不会白跑一次 finish。');
+  lines.push('', '## 4. 复现', '');
+  lines.push('```bash');
+  lines.push('node todo-summary.cjs run --days 30 --limit 500 --out /tmp/t --file --timing-report');
+  lines.push('```');
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * 取当前认证环境的 `baseUrl`（`weaver-work-cli --json auth status`），优先用 state.json 缓存，
+ * 避免同一次流水线里重复启动 CLI。browsertool 载荷的 `src` 必须跟着认证环境走，**禁止写死租户域名**。
+ */
+function resolveBaseUrl(state, dir) {
+  if (state.baseUrl) return state.baseUrl;
+  let baseUrl = '';
+  try {
+    const raw = execFileSync(CLI, ['--json', 'auth', 'status'], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      env: cliEnv(),
+    });
+    const parsed = JSON.parse(raw);
+    baseUrl = (parsed && ((parsed.data && parsed.data.baseUrl) || parsed.baseUrl)) || '';
+  } catch (error) {
+    baseUrl = '';
+  }
+  if (!baseUrl) {
+    console.error('✖ 取不到认证环境的 baseUrl（weaver-work-cli --json auth status），src 不能写死租户');
+    process.exit(1);
+  }
+  state.baseUrl = String(baseUrl).replace(/\/+$/, '');
+  fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
+  return state.baseUrl;
+}
+
+/**
+ * 把最终三键对象包成 browsertool 组件载荷（用户 2026-10-27 要求）。
+ * - `params.data` 放三键本身；`src` = 当前认证环境 baseUrl + `/workflow/list/todo`；
+ * - 数据段沿用调用方的紧凑文本（`requestData` 单行），只加缩进前缀、不重新序列化，
+ *   避免几千行 requestData 被展开成 4 倍体积；
+ * - 包裹完成后立刻 `JSON.parse` 自检，坏载荷不交给用户。
+ */
+function wrapBrowseToolPayload(dataText, baseUrl) {
+  const indentTail = (text, spaces) => text.split('\n')
+    .map((line, index) => (index === 0 ? line : ' '.repeat(spaces) + line))
+    .join('\n');
+  const src = `${String(baseUrl).replace(/\/+$/, '')}/workflow/list/todo`;
+  const text = [
+    '{',
+    '  "version": "1.0",',
+    '  "callId": "call-1",',
+    '  "toolId": "todo_summary",',
+    '  "arguments": {',
+    '    "type": "e10",',
+    '    "title": "待办摘要汇总",',
+    `    "src": ${JSON.stringify(src)},`,
+    '    "sdkRenderType": "drawer",',
+    '    "sdkOptions": {',
+    '      "compName": "ui.CorsComponent",',
+    '      "routerType": "MemoryRouter",',
+    '      "routerProps_pc": { "initialEntries": ["/"] },',
+    '      "routerProps_mobile": { "initialEntries": ["/"] },',
+    '      "params_pc": { "app": "@weapp/workflow", "compName": "Comp.WflTodoSummary", "clientType": "pc" },',
+    '      "params_mobile": { "app": "@weapp/workflow", "compName": "Comp.WflTodoSummary", "clientType": "mobile" },',
+    '      "params": {',
+    `        "data": ${indentTail(dataText, 8)}`,
+    '      }',
+    '    }',
+    '  }',
+    '}',
+  ].join('\n');
+  JSON.parse(text);
+  return `${text}\n`;
+}
+
+function exportFinal(result, dir, state, kept, opts = {}) {
+  const { limit, from, to } = state;
+  const excluded = (state.exclude || []).join('/');
+  const data = result.data;
+  const groupTotal = (data.wfIdGroup || []).reduce((sum, g) => sum + (Number(g.count) || 0), 0);
+  // CLI 已给 totalCount；缺了（旧版 CLI）就按各组 count 求和兜底，保证三个键恒定存在。
+  const totalCount = Number(data.totalCount ?? groupTotal) || 0;
+  const payload = {
+    smartSummaryTitle: data.smartSummaryTitle,
+    totalCount,
+    wfIdGroup: data.wfIdGroup,
+  };
+  const stamp = new Date().toISOString().slice(0, 10);
+  const scope = from && to
+    ? `${from}~${to}`
+    : limit
+      ? (kept === limit ? `前${limit}条` : `前${limit}条-剩${kept}条`)
+      : `全部${kept}条`;
+  const stampPart = from && to ? '' : `-${stamp}`;
+  const finalFile = path.join(dir, `待办汇总-${scope}${excluded ? `-排除${excluded}` : ''}${stampPart}.json`);
+  // browsertool 载荷的 src 跟着当前认证环境走（用户 2026-10-27 要求不写死租户）。
+  const baseUrl = resolveBaseUrl(state, dir);
+  const stats = groupStats(data.wfIdGroup);
+  const total = groupTotal;
+  console.log('\n最终结构（共 %d 条 / %d 组｜totalCount=%d）：', total, data.wfIdGroup.length, totalCount);
+  for (const row of stats.rows) {
+    console.log(`  ${row.title} | ${row.count} | ${row.display}${row.singles ? ` +单条${row.singles}` : ''}`);
+  }
+  // 叠加视图：优先组的条目同时留在工作流组里，所以 Σcount 会大于 totalCount（去重条数）。
+  console.log('\n自检：totalCount=%d（去重）｜Σcount=%d（含优先组叠加 %d）｜汇总项覆盖 %d + 单条 %d ｜ 空摘要 %d ｜ 文件 %s',
+    totalCount, total, Math.max(0, total - totalCount), stats.covered, stats.singles, stats.empty,
+    opts.writeFile ? finalFile : '（未生成，按交付规则只输出 <browsertool> 载荷）');
+  const meta = result.meta || {};
+  const steps = (meta.timing && meta.timing.steps) || [];
+  console.log('CLI 自报分段：%s', steps.map((s) => `${s.name}:${s.kind}=${fmt(s.durationMs)}`).join(' '));
+  // 交付用 JSON：requestData 压成单行、其余缩进，既合法又可读（10KB 级）
+  const lines = [
+    '{',
+    `  "smartSummaryTitle": ${JSON.stringify(payload.smartSummaryTitle)},`,
+    `  "totalCount": ${totalCount},`,
+    '  "wfIdGroup": [',
+  ];
+  payload.wfIdGroup.forEach((g, gi) => {
+    lines.push('    {');
+    lines.push(`      "id": ${JSON.stringify(g.id)},`);
+    lines.push(`      "topPriority": ${g.topPriority},`);
+    lines.push(`      "title": ${JSON.stringify(g.title)},`);
+    lines.push(`      "count": ${g.count},`);
+    lines.push(`      "defaultExpanded": ${g.defaultExpanded},`);
+    lines.push('      "displayItems": [');
+    g.displayItems.forEach((item, ii) => {
+      const tail = ii < g.displayItems.length - 1 ? ',' : '';
+      if (item.type === 'request') {
+        lines.push(`        {"type":"request","requestData":${JSON.stringify(item.requestData)}}${tail}`);
+        return;
+      }
+      lines.push('        {');
+      lines.push('          "type": "group",');
+      lines.push(`          "id": ${JSON.stringify(item.id)},`);
+      lines.push(`          "title": ${JSON.stringify(item.title)},`);
+      lines.push(`          "count": ${item.count},`);
+      lines.push(`          "summary": ${JSON.stringify(item.summary)},`);
+      lines.push(`          "defaultExpanded": ${item.defaultExpanded},`);
+      lines.push('          "requestDatas": [');
+      item.requestDatas.forEach((row, ri) => {
+        lines.push(`            ${JSON.stringify(row)}${ri < item.requestDatas.length - 1 ? ',' : ''}`);
+      });
+      lines.push('          ]');
+      lines.push(`        }${tail}`);
+    });
+    lines.push('      ]');
+    lines.push(`    }${gi < payload.wfIdGroup.length - 1 ? ',' : ''}`);
+  });
+  lines.push('  ]', '}');
+  // 落盘与 stdout 共用同一份载荷；data 段只保留三个业务键。
+  const finalText = wrapBrowseToolPayload(lines.join('\n'), baseUrl);
+  // 用户 2026-10-27 定稿：交付 = 回复里内联 <browsertool> 整块，**不再生成 JSON 文件**。
+  // `--file` 仅保留作调试（写一份纯载荷 JSON），交付流程不再使用它。
+  if (opts.writeFile) fs.writeFileSync(finalFile, finalText);
+  const delivery = `<browsertool>\n${finalText.trimEnd()}\n</browsertool>`;
+  console.log('\n[JSON_BEGIN]');
+  console.log(delivery);
+  console.log('[JSON_END]');
+  console.log('载荷字节数：%d（含 <browsertool> 标签）', Buffer.byteLength(delivery));
+  // 用户 2026-10-27 要求：不再产出「耗时说明 md」交付物，耗时只在控制台打一段摘要。
+  // 计时与统计逻辑（state 各阶段耗时、buildTimingReport 的算法）保持不变，只是输出形态变了。
+  if (opts.timingReport) {
+    const conclusion = buildTimingReport(state, result)
+      .split('## 2. 分阶段')[0]
+      .split('\n')
+      .filter((line) => line.startsWith('- '))
+      .map((line) => `  ${line.slice(2).replace(/\*\*/g, '')}`)
+      .join('\n');
+    console.log('\n耗时摘要（仅 CLI 执行链路，不含模型往返）：');
+    console.log(conclusion);
+  }
+  return opts.writeFile ? finalFile : null;
+}
+
+/**
+ * 默认由 CLI 走确定性分组的类型（请假 / 财务）。没有侧重点时它们不需要 AI 计划，
+ * 但**用户给了适用于本类型的侧重点时必须给计划**，否则这里会把组藏起来、白丢一次分组。
+ * 2026-10-27 修：原实现只看组名就跳过，导致 `--focus "请假类型、报销类型"` 下
+ * 请假/报销组仍被标成「无需分组」并把条目藏掉。
+ */
+const RULE_KINDS = [
+  { kind: 'leave', pattern: /(请假|休假|年假|调休|病假|事假|婚假|产假|陪产|丧假|探亲假|工伤假|哺乳假|公休)/u },
+  { kind: 'finance', pattern: /(报销|费用|付款|请款|借款|发票|差旅|对公|资金|核销)/u },
+];
+
+/** 侧重点命中了哪些「默认确定性」类型的维度（与 businessRules 的意图表同口径：只认类型词）。 */
+function focusCoversKinds(focusText) {
+  const text = String(focusText || '').trim();
+  if (!text) return new Set();
+  return new Set(RULE_KINDS.filter((rule) => rule.pattern.test(text)).map((rule) => rule.kind));
+}
+
+/** 本组是否属于某个默认确定性类型。 */
+function kindOfTitle(title) {
+  const hit = RULE_KINDS.find((rule) => rule.pattern.test(String(title || '')));
+  return hit ? hit.kind : '';
+}
+
+function cmdPrep(args) {
+  const limit = Number(args.limit || 0);
+  const days = Number(args.days || 0);
+  const exclude = args.exclude && args.exclude !== true ? String(args.exclude).split(',').map((x) => x.trim()).filter(Boolean) : [];
+  const dir = args.out && args.out !== true ? String(args.out) : `/tmp/todo-summary-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+  fs.mkdirSync(dir, { recursive: true });
+
+  const startedAt = nowIso();
+  const input = { stage: 'collect', limit: limit || 500 };
+  // 小分类（待处理 / 待阅 / 全部…）：该环境 `category=todo` 默认是「全部」，会把待阅也算进来；
+  // 要「待阅除外」必须显式传 `--sub-category 待处理`。
+  if (args['sub-category'] && args['sub-category'] !== true) {
+    input.subCategory = String(args['sub-category']);
+  }
+  // 摘要字数口径要带进 collect：否则缓存命中按默认 50 字判定，
+  // 用户要求「10 字以内」时仍会回填旧的长摘要（2026-10-22 实测踩到）。
+  if (args['summary-chars'] && args['summary-chars'] !== true) {
+    input.summaryMaxChars = Number(args['summary-chars']);
+  }
+  if (args.focus && args.focus !== true) input.groupFocus = String(args.focus);
+  if (args.from && args.to) {
+    // 指定区间（含两端），如 --from 2026-10-01 --to 2026-10-31
+    input.receiveTime = `${args.from} ${args.to}`;
+  } else if (days > 0) {
+    const end = new Date();
+    const start = new Date(end.getTime() - days * 24 * 3600 * 1000);
+    const fmtDate = (d) => d.toISOString().slice(0, 10);
+    input.receiveTime = `${fmtDate(start)} ${fmtDate(end)}`;
+  }
+  const t0 = Date.now();
+  const collect = runStage(input, dir, 'collect');
+  const collectWallMs = Date.now() - t0;
+  // **两个口径必须分开**（性能调优时最容易看错的地方）：
+  //  - collectWallMs：脚本进程视角的墙钟，含 node 启动 + 模块加载（沙箱下 5~7s）；
+  //  - collectMs：CLI 自报的 collect 阶段内部耗时，只含真实业务（取数 + 归一）。
+  const collectStep = ((collect.meta && collect.meta.timing && collect.meta.timing.steps) || [])
+    .find((step) => step && step.name === 'collect');
+  const collectMs = collectStep && Number.isFinite(collectStep.durationMs) ? collectStep.durationMs : collectWallMs;
+
+  const all = collect.data.items || [];
+  const kept = exclude.length ? all.filter((row) => !exclude.includes(String(row.workflowName || ''))) : all;
+  const dropped = all.length - kept.length;
+
+  // 组结构直接用 CLI 返回的 wfIdGroup（已做 priority 抽取，不能再自己按 workflowName 复算，
+  // 否则会把被抽进「建议优先处理」的条目重复计入原流程）。
+  // 注意：wfIdGroup[].requestDatas 里**没有 workflowName**，要按 requestId 从 items 回查，
+  // 否则「按流程名剔除」对被 priority 抽走的条目会失效。
+  const workflowNameById = new Map();
+  for (const row of all) workflowNameById.set(String(row.requestId || ''), String(row.workflowName || ''));
+  const isExcluded = (row) => exclude.includes(workflowNameById.get(String(row.requestId || '')) || '');
+
+  const planGroups = [];
+  for (const group of collect.data.wfIdGroup || []) {
+    if (exclude.includes(String(group.title))) continue;
+    const rows = (group.requestDatas || []).filter((row) => !isExcluded(row));
+    if (rows.length === 0) continue;
+    planGroups.push({
+      groupId: String(group.id),
+      title: group.title,
+      count: rows.length,
+      rows: rows.map((row, index) => ({
+        idx: index + 1,
+        requestId: String(row.requestId || ''),
+        title: String(row.requestNameTitle || ''),
+      })),
+    });
+  }
+
+  // 有侧重点时 collect 已经把流程详情数据作为分组素材放进 `groupingBrief[].items[].fields`。
+  // prep 直接把它挑几类关键字段打出来：模型据此分桶，不必再另起一轮去翻详情缓存。
+  const HINT_FIELD = /(类型|类别|假别|假种|天数|金额|说明)/u;
+  const fieldHintById = new Map();
+  for (const brief of collect.data.groupingBrief || []) {
+    for (const item of brief.items || []) {
+      const fields = Array.isArray(item.fields) ? item.fields : [];
+      const seenValues = new Set();
+      const picked = fields
+        .filter((f) => HINT_FIELD.test(String(f.fieldName || '')))
+        .filter((f) => {
+          const value = String(f.value || '').replace(/\s+/g, ' ').trim();
+          if (!value || seenValues.has(value)) return false;
+          seenValues.add(value);
+          return true;
+        })
+        .slice(0, 3)
+        .map((f) => `${f.fieldName}=${String(f.value || '').replace(/\s+/g, ' ').trim().slice(0, 20)}`);
+      if (picked.length > 0) fieldHintById.set(String(item.requestId || ''), picked.join(' · '));
+    }
+  }
+
+  fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify({
+    dir, startedAt, limit, days, from: args.from || null, to: args.to || null, exclude, subCategory: input.subCategory || null, collectMs, collectWallMs,
+    groupFocus: args.focus && args.focus !== true ? String(args.focus) : null,
+    summaryMaxChars: args["summary-chars"] ? Number(args["summary-chars"]) : null,
+    groupSummaryMaxChars: args["group-summary-chars"] ? Number(args["group-summary-chars"]) : null,
+    fetched: all.length, kept: kept.length, dropped,
+    planGroups,
+  }));
+  fs.writeFileSync(path.join(dir, 'items.json'), JSON.stringify(kept, null, 2));
+
+  console.log('取数：%d 条（%s）｜剔除 %d 条（%s）｜保留 %d 条｜collect 内部 %s / 含进程启动 %s',
+    all.length, limit ? `前 ${limit} 条` : '全部', dropped, exclude.join('/') || '无', kept.length,
+    fmt(collectMs), fmt(collectWallMs));
+  console.log('输出目录：%s\n', dir);
+  const focusKinds = focusCoversKinds(args.focus && args.focus !== true ? args.focus : '');
+  for (const group of planGroups) {
+    // 只有「默认确定性类型 + 侧重点没覆盖本类型」才算无需分组；被覆盖时照常列出条目。
+    const kind = kindOfTitle(group.title);
+    const skip = group.groupId === 'priority' || group.count <= 1 || (kind !== '' && !focusKinds.has(kind));
+    console.log(`=== ${group.groupId} | ${group.title} | ${group.count}${skip ? ' [无需分组]' : ''}`);
+    if (skip) continue;
+    for (const row of group.rows) {
+      const hint = fieldHintById.get(row.requestId) || '';
+      // 提示放在**同一行**：两行格式容易让人（和模型）回头去匹配标题，而标题里往往没有类型词。
+      console.log(`${row.idx}\t${hint ? `[${hint}] ` : ''}${row.title.replace(/\s+/g, ' ').slice(0, 46)}`);
+    }
+  }
+  console.log('\n下一步：node %s build --dir %s', path.basename(__filename), dir);
+  console.log('（只有内部留言组、或用户给了侧重点时才需要再补 --plan <aiGroups.json>；其余走确定性分组）');
+}
+
+function cmdBuild(args) {
+  const dir = String(args.dir);
+  const planFile = args.plan !== undefined && args.plan !== true ? String(args.plan) : '';
+  const state = readJson(path.join(dir, 'state.json'));
+  const kept = readJson(path.join(dir, 'items.json'));
+  const planGroups = state.planGroups || [];
+  const countById = new Map(planGroups.map((g) => [g.groupId, g.count]));
+  // `--plan` 可选：其他类默认不按标题二次分组，很多批次根本不需要 AI 计划。
+  // 不传时直接走 CLI 确定性分组（等价于 aiGroups 未传）。
+  let aiGroups;
+  if (planFile) {
+  aiGroups = readJson(planFile);
+
+  // 覆盖校验：每个 groupId 的 1..count 全覆盖、无重复；count 取 CLI 口径（priority 已抽取）
+  const byGroup = new Map();
+  for (const entry of aiGroups) {
+    if (!entry || !entry.groupId || !Array.isArray(entry.seq)) {
+      console.error('✖ aiGroups 元素必须是 {groupId,title,seq:[...]}'); process.exit(1);
+    }
+    if (!countById.has(String(entry.groupId))) {
+      console.error(`✖ 未知 groupId ${entry.groupId}（合法值见 state.json 的 planGroups）`); process.exit(1);
+    }
+    const set = byGroup.get(entry.groupId) || new Set();
+    for (const n of entry.seq) {
+      if (set.has(n)) { console.error(`✖ groupId ${entry.groupId} 的 seq ${n} 重复`); process.exit(1); }
+      set.add(n);
+    }
+    byGroup.set(entry.groupId, set);
+  }
+  for (const [groupId, seqs] of byGroup) {
+    const count = countById.get(groupId);
+    const miss = [];
+    for (let i = 1; i <= count; i += 1) if (!seqs.has(i)) miss.push(i);
+    if (miss.length) {
+      const name = (planGroups.find((g) => g.groupId === groupId) || {}).title || groupId;
+      console.error(`✖ ${name} 缺 ${miss.length} 条：${miss.slice(0, 12).join(',')}`);
+      process.exit(1);
+    }
+  }
+  const focusKinds = focusCoversKinds(state.groupFocus);
+  for (const group of planGroups) {
+    if (countById.get(group.groupId) <= 1 || group.groupId === 'priority') continue;
+    // 请假/财务默认由 CLI 阈值兜底，不需要模型给子组；但**侧重点覆盖了本类型时必须给**，
+    // 否则这里静默跳过，用户要的「按请假类型/报销类型分组」就白丢了。
+    const kind = kindOfTitle(group.title);
+    if (kind !== '' && !focusKinds.has(kind)) continue;
+    if (!byGroup.has(group.groupId)) console.log('⚠ %s（%d 条）没有给子组，将整体作为一个汇总项', group.title, group.count);
+  }
+  fs.writeFileSync(path.join(dir, 'aiGroups.json'), JSON.stringify(aiGroups, null, 2));
+  }
+
+  const t = Date.now();
+  const sg = runStage({
+    stage: 'smartGroup',
+    items: kept,
+    ...(aiGroups !== undefined ? { aiGroups } : {}),
+    withDetailContext: true,
+    ...(state.groupFocus ? { groupFocus: state.groupFocus } : {}),
+    ...(state.summaryMaxChars ? { summaryMaxChars: state.summaryMaxChars } : {}),
+    skillTiming: { startedAt: state.startedAt, steps: [{ name: 'collect', kind: 'cli', durationMs: state.collectMs }] },
+  }, dir, 'smartgroup');
+  fs.writeFileSync(path.join(dir, 'smartgroup.json'), JSON.stringify(sg));
+  const smartGroupMs = Date.now() - t;
+
+  const batches = sg.data.summaryBatches || [];
+  const pending = batches.flatMap((b) => b.items || []);
+  const stats = sg.data.summaryStats || {};
+  const sgInternal = cliStageMs(sg, 'smartGroup');
+  console.log('smartGroup 内部 %s / 含进程启动 %s｜%d 条 / %d 组｜prefilled=%s｜待写摘要 %d 条',
+    sgInternal === null ? '-' : fmt(sgInternal), fmt(smartGroupMs),
+    sg.data.wfIdGroup.reduce((a, g) => a + g.count, 0), sg.data.wfIdGroup.length, stats.prefilled, pending.length);
+  // 回写耗时（供 `finish --timing-report` 一次性生成耗时说明，免得多跑一轮查询）
+  state.smartGroupWallMs = smartGroupMs;
+  state.smartGroupInternalMs = sgInternal;
+  fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
+
+  if (pending.length === 0) {
+    exportFinal(sg, dir, state, kept.length, { writeFile: args.file === true, timingReport: args['timing-report'] });
+    return;
+  }
+  const summaryTarget = pending[0] && pending[0].suggestedMaxChars ? pending[0].suggestedMaxChars : 50;
+  console.log(`\n待写摘要（把结果写成 aiSummaries.json，元素 {requestId,summary}，约 ${summaryTarget} 字）：`);
+  for (const item of pending) {
+    console.log(`### ${item.requestId}`);
+    console.log(`T: ${String(item.requestNameTitle || '').slice(0, 70)}`);
+    console.log(`C: ${String(item.context || '').replace(/\s+/g, ' ').slice(0, 240)}`);
+  }
+  console.log('\n下一步：node %s finish --dir %s --summaries <aiSummaries.json>', path.basename(__filename), dir);
+}
+
+function cmdFinish(args) {
+  const dir = String(args.dir);
+  const state = readJson(path.join(dir, 'state.json'));
+  const kept = readJson(path.join(dir, 'items.json'));
+  // `aiGroups.json` 可能不存在（build 没传 --plan 时就是确定性分组），此时按「未传 aiGroups」处理。
+  const planPath = path.join(dir, 'aiGroups.json');
+  const aiGroups = fs.existsSync(planPath) ? readJson(planPath) : undefined;
+  const sg = readJson(path.join(dir, 'smartgroup.json'));
+
+  // 即使没传 --summaries 也要跑一次 summary 阶段：这样才能让**摘要缓存**回填
+  // （否则直接导出 smartgroup.json 的半成品，会出现一堆空摘要）。传了 aiSummaries 就额外落位。
+  const aiSummaries = args.summaries && args.summaries !== true ? readJson(String(args.summaries)) : [];
+  const t = Date.now();
+  const result = runStage({
+    stage: 'summary',
+    items: kept,
+    ...(aiGroups !== undefined ? { aiGroups } : {}),
+    withDetailContext: true,
+    wfIdGroup: sg.data.wfIdGroup,
+    aiSummaries,
+    withGroupSummaryContext: true,
+    ...(state.summaryMaxChars ? { summaryMaxChars: state.summaryMaxChars } : {}),
+    ...(state.groupSummaryMaxChars ? { groupSummaryMaxChars: state.groupSummaryMaxChars } : {}),
+    skillTiming: { startedAt: state.startedAt, steps: [{ name: 'collect', kind: 'cli', durationMs: state.collectMs }] },
+  }, dir, 'summary');
+  fs.writeFileSync(path.join(dir, 'summary.json'), JSON.stringify(result));
+  const summaryInternal = cliStageMs(result, 'summary');
+  const summaryWallMs = Date.now() - t;
+  state.summaryWallMs = summaryWallMs;
+  state.summaryInternalMs = summaryInternal;
+  fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
+  console.log('summary 内部 %s / 含进程启动 %s（回填 %d 条，其余走缓存预填）',
+    summaryInternal === null ? '-' : fmt(summaryInternal), fmt(summaryWallMs), aiSummaries.length);
+  let finalResult = result;
+  const groupBatches = result.data.groupSummaryBatches || [];
+  if (groupBatches.length > 0) {
+    const groupSummariesFile = args['group-summaries'] && args['group-summaries'] !== true
+      ? String(args['group-summaries'])
+      : null;
+    if (groupSummariesFile) {
+      // 组摘要必须由模型写、且每轮重算；这里只是把「回填」并进同一次命令，省掉一次模型往返。
+      const aiGroupSummaries = readJson(groupSummariesFile);
+      const t2 = Date.now();
+      const gs = runStage({
+        smartSummaryTitle: result.data.smartSummaryTitle,
+        totalCount: result.data.totalCount,
+        wfIdGroup: result.data.wfIdGroup,
+        aiGroupSummaries,
+      }, dir, 'groupsummary');
+      state.groupSummaryWallMs = Date.now() - t2;
+      state.groupSummaryInternalMs = cliStageMs(gs, 'groupSummary');
+      fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
+      fs.writeFileSync(path.join(dir, 'groupsummary.json'), JSON.stringify(gs));
+      const filled = (gs.meta && gs.meta.groupSummarized) || 0;
+      const empty = (gs.meta && gs.meta.groupEmpty) || 0;
+      console.log('groupSummary 内部 %s / 含进程启动 %s（回填 %d 个汇总项，空 %d）',
+        state.groupSummaryInternalMs === null ? '-' : fmt(state.groupSummaryInternalMs), fmt(state.groupSummaryWallMs), filled, empty);
+      const gsWarnings = (gs.meta && gs.meta.warnings) || [];
+      for (const text of gsWarnings) console.log('  ⚠ %s', text);
+      finalResult = gs;
+    } else {
+      console.log('\n⚠ 还有 %d 个组摘要素材待模型生成（groupSummary 阶段）：', groupBatches.length);
+      for (const batch of groupBatches) console.log(JSON.stringify(batch).slice(0, 400));
+      console.log('  → 写成 [{groupId,summary}] 后加 `--group-summaries <file>` 重跑本命令，可在同一次调用里回填');
+    }
+  }
+  exportFinal(finalResult, dir, state, kept.length, { writeFile: args.file === true, timingReport: args['timing-report'] });
+  console.log('总耗时（脚本口径）：%s', fmt(Date.now() - Date.parse(state.startedAt)));
+}
+
+/**
+ * `run`：把 prep + build（+ 无待写摘要时自动 finish）串成**一次调用**。
+ *
+ * 为什么要这个命令：每一步都要模型读输出再决定下一步，每次往返在长上下文下要 20~35s。
+ * 一次汇总原本要 9 次往返（实测 4m58s），其中 CLI 只占 25s —— 合并阶段是端到端提速的关键。
+ *
+ * 有待写摘要时会停下并打印素材：那部分必须模型写，写完跑 `finish` 即可，不用重跑取数与分组。
+ */
+function cmdRun(args) {
+  const dir = args.out && args.out !== true
+    ? String(args.out)
+    : `/tmp/todo-summary-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
+  cmdPrep({ ...args, out: dir });
+  cmdBuild({ ...args, dir });
+  const sg = readJson(path.join(dir, 'smartgroup.json'));
+  const pending = ((sg.data.summaryBatches || []).flatMap((batch) => batch.items || []));
+  if (pending.length > 0) {
+    console.log('\n⚠ 有 %d 条待写摘要：写成 aiSummaries.json 后跑 finish（**不用重跑** collect/smartGroup）', pending.length);
+    console.log('  node %s finish --dir %s --summaries <aiSummaries.json> --file --timing-report', path.basename(__filename), dir);
+    return;
+  }
+  // 没有待写摘要 ⇒ 终态可以立刻出，省掉一次约 7s 的进程启动
+  cmdFinish({ dir, file: args.file === true, 'timing-report': args['timing-report'], 'group-summaries': args['group-summaries'] });
+}
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+if (cmd === 'prep') cmdPrep(args);
+else if (cmd === 'build') cmdBuild(args);
+else if (cmd === 'finish') cmdFinish(args);
+else if (cmd === 'run') cmdRun(args);
+else {
+  console.log('用法：node ' + path.basename(__filename) + ' <run|prep|build|finish> [options]');
+  console.log('  run    --days 30 --limit 500 [--out DIR] [--file] [--timing-report]   # 一次跑完 prep+build（无待写摘要时连 finish 一起）');
+  console.log('  prep   --limit 100 [--exclude 内部留言] [--days 1460] [--sub-category 待处理] [--out DIR]');
+  console.log('  build  --dir DIR [--plan aiGroups.json]   # 不传 plan = 直接走确定性分组');
+  console.log('  finish --dir DIR [--summaries aiSummaries.json] [--group-summaries aiGroupSummaries.json] [--file] [--timing-report]');
+  console.log('  提示：`--timing-report` 会在控制台打一段耗时摘要（阶段墙钟 / CLI 内部），**不产出 md**');
+  process.exit(2);
+}