weaver-work-cli 0.1.38 → 0.1.39

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

@@ -6,7 +6,7 @@
  * 避免每次现场拼脚本，也避免多跑一次 stage=group 进程（每次 CLI 启动约 6~7s）。
  *
  * 用法：
- *   node todo-summary.cjs prep   --limit 100 [--exclude 内部留言] [--days 365] [--out DIR]
+ *   node todo-summary.cjs prep   [--limit 500] [--exclude 内部留言] [--days 365 | --from A --to B] [--out DIR]   # 用户没说时间段就都不传 = 不限时间取前 500 条
  *       → 取数、按 workflowName 剔除指定流程、打印分组素材（模型据此做二次分组）
  *   node todo-summary.cjs build  --dir DIR --plan aiGroups.json
  *       → 校验 1..count 全覆盖 → smartGroup；若还有待写摘要则打印，否则直接导出终态
@@ -17,8 +17,17 @@
  */
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 
+// 缓存与 aigroup 规则都锚定「当前 skill」（2026-11-01 用户定稿）：本脚本就住在
+// <skillDir>/tools/ 下，把自身 skill 目录显式指给 CLI——生成与提取一律用当前 skill
+// 的 cache/，不再走多安装发现排名（否则改名的副本会被旧安装的缓存抢走）。
+// 用户已显式设置时不覆盖。
+if (!process.env.WEAVER_WORK_CLI_SKILL_DIR) {
+  process.env.WEAVER_WORK_CLI_SKILL_DIR = path.resolve(__dirname, '..');
+}
+
 /**
  * CLI 可执行入口（跨平台）。
  *
@@ -169,9 +178,10 @@ function groupStats(wfIdGroup) {
 /**
  * 导出最终结构。
  *
- * 交付形态（用户 2026-10-22 硬规则）：**只在对话里输出 JSON + 耗时，不产物理文件**。
- * 所以默认走「stdout-only」：把最终结构的 JSON 打到 stdout 的 `[JSON_BEGIN]/[JSON_END]` 之间，
- * 由 Agent 原样贴进回复；只有显式传 `--file` 才写成 `待办汇总-*.json`（兼容旧用法/调试）。
+ * 交付形态：stdout 输出 `<browsertool>` 载荷（`[JSON_BEGIN]/[JSON_END]` 之间），
+ * 由 Agent 原样贴进回复；三键数据本体另存 `final.data.json`（交付文件复制它的，
+ * 命名 `<用户名>_<时间戳>.json` 由 Agent 侧按 references §6.1 拼写）。
+ * 旧 `--file`（写 `待办汇总-*.json` 外框归档）已于 2026-11-01 删除：文件名与内容都是旧口径，易误当交付物。
  *
  * 顶层键固定三个：`smartSummaryTitle` / `totalCount` / `wfIdGroup`（用户 2026-10-25 要求加
  * `totalCount` = 当前这批数据的总条数，与各大分组 `count` 之和一致）。
@@ -220,7 +230,7 @@ function buildTimingReport(state, result) {
   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('node todo-summary.cjs run --days 30 --limit 500 --out /tmp/t --timing-report');
   lines.push('```');
   return `${lines.join('\n')}\n`;
 }
@@ -311,7 +321,9 @@ function sleepSync(ms) {
  * - 快照按目录 mtime 计空闲，超时由服务端自己删；进程在所有快照过期且无请求后才退出。
  */
 const SERVE_ROOT = path.join(require('node:os').tmpdir(), 'weaver-work-cli-serve');
-const SERVE_VERSION = '3';
+const SERVE_VERSION = '4';
+/** v4 服务的发布密钥：ensureServeServer 从 current.json 读出，publishSnapshot 发布时回传。 */
+let servePublishKey = '';
 
 /**
  * 同步探一次本地数据源的 `/health`：通就返回解析后的 JSON，不通返回 null。
@@ -362,6 +374,7 @@ function ensureServeServer(portOption) {
         // 先探活：既验「真有人在这端口上应答」，也验「应答的是不是我们这个版本的自己」。
         const health = probeHealth(cur.port);
         if (health && health.ok === true && String(health.version) === SERVE_VERSION) {
+          servePublishKey = String(cur.publishKey || '');
           return cur.port;
         }
         if (health && health.ok === true) {
@@ -390,7 +403,10 @@ function ensureServeServer(portOption) {
     if (fs.existsSync(registryFile)) {
       try {
         const info = JSON.parse(fs.readFileSync(registryFile, 'utf8'));
-        if (info && info.version === SERVE_VERSION && info.port && info.pid === child.pid) return info.port;
+        if (info && info.version === SERVE_VERSION && info.port && info.pid === child.pid) {
+          servePublishKey = String(info.publishKey || '');
+          return info.port;
+        }
       } catch { /* 文件正在写入，稍后重试 */ }
     }
     sleepSync(120);
@@ -405,6 +421,48 @@ function publishSnapshot(dir, portOption) {
   const port = ensureServeServer(portOption);
   if (!port) return null;
   const token = require('node:crypto').randomBytes(12).toString('hex');
+  const url = `http://127.0.0.1:${port}/s/${token}/todo.json`;
+  const body = fs.readFileSync(dataFile, 'utf8');
+
+  // v4 主通路：把 JSON 原文 POST 进服务内存（带发布密钥）。
+  // 服务端不再读磁盘 ⇒ 不受「常驻进程读权限被沙箱回收」的影响，链接跨命令/跨轮次稳定。
+  // POST 用独立的极短 node 子进程同步完成（与 probeHealth 同款手法：主进程 Atomics 阻塞时
+  // async 回调排不上队，只能用子进程）；body 走 stdin 传给子进程，避免命令行长度问题。
+  const postCode = [
+    "const http=require('node:http');",
+    "const fs=require('node:fs');",
+    'const key=process.argv[1];',
+    'const port=Number(process.argv[2]);',
+    'const token=process.argv[3];',
+    "const body=fs.readFileSync(0,'utf8');",
+    "const req=http.request({host:'127.0.0.1',port,path:'/s/'+token+'/todo.json',method:'POST',",
+    "  headers:{'content-type':'application/json','x-publish-key':key,'content-length':Buffer.byteLength(body)},timeout:10000},",
+    '  (res)=>{let b="";res.setEncoding("utf8");',
+    '    res.on("data",(d)=>{b+=d;});',
+    '    res.on("end",()=>{process.stdout.write(b);process.exit(res.statusCode===200?0:3);});',
+    '  });',
+    "req.on('timeout',()=>{req.destroy();process.exit(2);});",
+    "req.on('error',()=>process.exit(2));",
+    'req.end(body);',
+  ].join('');
+  try {
+    const result = execFileSync(
+      process.execPath,
+      ['-e', postCode, servePublishKey, String(port), token],
+      { input: body, encoding: 'utf8', timeout: 20000, maxBuffer: 16 * 1024 * 1024, env: cliEnv() },
+    );
+    const parsed = JSON.parse(result);
+    if (parsed && parsed.ok === true) {
+      try {
+        fs.writeFileSync(path.join(dir, 'serve.json'), JSON.stringify({
+          url, token, port, mode: 'memory', bytes: parsed.bytes,
+        }, null, 2));
+      } catch { /* 只是排错用的旁路文件 */ }
+      return url;
+    }
+  } catch { /* POST 失败 ⇒ 回落写文件方式（旧服务兼容） */ }
+
+  // 回落：老路径——写快照文件，由服务端读磁盘（v3 服务或 POST 失败时才走这里）。
   const snapDir = path.join(SERVE_ROOT, 'snapshots', token);
   fs.mkdirSync(snapDir, { recursive: true });
   // 先拷到临时名再拷成正式名：沙箱会拒绝对家目录做 rename（EPERM），copyFile 不受限；
@@ -413,16 +471,57 @@ function publishSnapshot(dir, portOption) {
   fs.copyFileSync(dataFile, tmp);
   fs.copyFileSync(tmp, path.join(snapDir, 'todo.json'));
   try { fs.unlinkSync(tmp); } catch { /* 残留也无害 */ }
-  const url = `http://127.0.0.1:${port}/s/${token}/todo.json`;
   try {
-    fs.writeFileSync(path.join(dir, 'serve.json'), JSON.stringify({ url, token, port, snapshotDir: snapDir }, null, 2));
+    fs.writeFileSync(path.join(dir, 'serve.json'), JSON.stringify({ url, token, port, mode: 'file' }, null, 2));
   } catch { /* 只是排错用的旁路文件 */ }
   return url;
 }
 
+/**
+ * 交付文件名的用户名（2026-11-01 用户拍板）：`auth whoami` 拿 employeeId →
+ * `hrm run hrm.employee.detail` 取 `username`（认证系统当前登录人，不是本机账号）。
+ * 结果缓存在 state.json——同一次流水线只查一次；查不到返回 null（调用方退回手工命名）。
+ */
+function resolveDeliverUsername(state, dir) {
+  if (state.deliveryUsername) return state.deliveryUsername;
+  try {
+    const who = JSON.parse(runCli(['--json', 'auth', 'whoami'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, env: cliEnv() }));
+    const employeeId = String((who.data || who).employeeId || '').trim();
+    if (!employeeId) return null;
+    const raw = runCli(['--json', 'hrm', 'run', 'hrm.employee.detail', '--input-json', JSON.stringify({ id: employeeId })], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, env: cliEnv() });
+    const detail = JSON.parse(raw);
+    const username = String((detail.data || {}).username || '').trim();
+    if (!username) return null;
+    state.deliveryUsername = username;
+    fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
+    return username;
+  } catch {
+    return null;
+  }
+}
+
+/** 规则文件缓存（同一进程只读一次）。 */
+let aigroupRuleFileCache = null;
+function loadAigroupRuleFile() {
+  if (aigroupRuleFileCache) return aigroupRuleFileCache;
+  try {
+    aigroupRuleFileCache = JSON.parse(fs.readFileSync(path.join(path.resolve(__dirname, '..'), 'aigroup', 'default.json'), 'utf8'));
+  } catch {
+    aigroupRuleFileCache = { rules: [] };
+  }
+  return aigroupRuleFileCache;
+}
+
+/** 组名 → 该规则的 summaryRequiredFields（needSummary:false 的组不校验）。 */
+function requiredFieldsFor(title) {
+  const rules = loadAigroupRuleFile().rules || [];
+  const rule = rules.find((r) => (Array.isArray(r.workflowName) ? r.workflowName : [r.workflowName])
+    .some((name) => name && name !== '*' && (title.includes(String(name)) || String(name).includes(title))));
+  if (!rule || rule.needSummary === false) return [];
+  return Array.isArray(rule.summaryRequiredFields) ? rule.summaryRequiredFields.filter((f) => typeof f === 'string' && f.trim()) : [];
+}
+
 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 求和兜底，保证三个键恒定存在。
@@ -432,26 +531,89 @@ function exportFinal(result, dir, state, kept, opts = {}) {
     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;
+  // ── 交付硬闸门（2026-11-01 用户拍板）：缺环节 / 静默降级出不了交付物，只有显式豁免才放行 ──
+  const allowEmpty = opts.allowEmptySummary === true;
+  const detailFailed = Number(opts.detailFailed) || 0;
+  const groupEmpty = Number(opts.groupEmpty) || 0;
+  if (!allowEmpty && stats.empty > 0) {
+    const emptyIds = [];
+    for (const group of data.wfIdGroup || []) {
+      for (const item of group.displayItems || []) {
+        for (const row of item.type === 'request' ? [item.requestData] : (item.requestDatas || [])) {
+          if (row && row.requestId && !String(row.summary || '').trim() && !emptyIds.includes(row.requestId)) emptyIds.push(row.requestId);
+        }
+      }
+    }
+    console.error('\n✖ 交付拦截：仍有 %d 条单条摘要为空（多为 --summaries 漏 id / 摘要缓存未回填）。缺失 requestId 前 10 个：%s%s',
+      stats.empty, emptyIds.slice(0, 10).join(', '), emptyIds.length > 10 ? ' …' : '');
+    console.error('  → 补全 --summaries 后重跑 finish，或加 --allow-empty-summary 显式豁免。');
+    process.exit(1);
+  }
+  if (!allowEmpty && groupEmpty > 0) {
+    console.error('\n✖ 交付拦截：仍有 %d 个组摘要为空（--group-summaries 漏了这些 groupId）。补全后重跑，或加 --allow-empty-summary 显式豁免。', groupEmpty);
+    process.exit(1);
+  }
+  if (!(opts.allowDetailFail === true) && detailFailed > 0) {
+    console.error('\n✖ 交付拦截：详情取数失败 %d 条——这些条目的摘要只能靠标题兜底，内容可能不完整（防"静默降级+单样本外推"）。排查登录态/详情缓存后重跑，或加 --allow-detail-fail 显式豁免。', detailFailed);
+    process.exit(1);
+  }
+  // ⑤ 降级话术黑名单（2026-11-01）：摘要正文出现"未在标题体现/详见流程"这类表述，
+  //    说明执行方把「自己没取到」写成了「业务对象没有」——按模板回查详情补齐后重写。
+  const DEGRADE_PHRASES = ['未在标题体现', '标题未体现', '标题里没有', '详见流程', '详见详情', '待确认'];
+  const degraded = [];
+  for (const group of data.wfIdGroup || []) {
+    for (const item of group.displayItems || []) {
+      for (const row of item.type === 'request' ? [item.requestData] : (item.requestDatas || [])) {
+        const text = String((row && row.summary) || '');
+        const hit = DEGRADE_PHRASES.find((phrase) => text.includes(phrase));
+        if (hit && row.requestId) degraded.push({ requestId: String(row.requestId), phrase: hit });
+      }
+    }
+  }
+  if (!allowEmpty && degraded.length > 0) {
+    console.error('\n✖ 交付拦截：%d 条摘要含降级话术（把取数失败写成业务信息缺失）：%s%s',
+      degraded.length,
+      degraded.slice(0, 5).map((x) => `${x.requestId.slice(-6)}[${x.phrase}]`).join(' '),
+      degraded.length > 5 ? ' …' : '');
+    console.error('  → 按模板回查详情缓存或 workflow.detail 补齐要素后重写，或加 --allow-empty-summary 显式豁免。');
+    process.exit(1);
+  }
+  // ⑥ 要素级校验（2026-11-01 用户拍板 P2）：规则声明了 summaryRequiredFields 的组，
+  //    每条摘要必须包含全部要素关键字，缺任一即拒绝导出（"模板要素优先于字数偏好"的机器化）。
+  const missingFields = [];
+  for (const group of data.wfIdGroup || []) {
+    const required = requiredFieldsFor(String(group.title || ''));
+    if (!required.length) continue;
+    for (const item of group.displayItems || []) {
+      for (const row of item.type === 'request' ? [item.requestData] : (item.requestDatas || [])) {
+        if (!row || !row.requestId) continue;
+        const text = String(row.summary || '');
+        if (!text.trim()) continue; // 空摘要由闸门①负责
+        const missing = required.filter((keyword) => !text.includes(keyword));
+        if (missing.length > 0) missingFields.push({ requestId: String(row.requestId), missing });
+      }
+    }
+  }
+  if (!allowEmpty && missingFields.length > 0) {
+    console.error('\n✖ 交付拦截：%d 条摘要缺模板要素（要素级校验）：%s%s',
+      missingFields.length,
+      missingFields.slice(0, 5).map((x) => `${x.requestId.slice(-6)}缺[${x.missing.join(',')}]`).join(' '),
+      missingFields.length > 5 ? ' …' : '');
+    console.error('  → 按模板回查详情补齐要素后重写，或加 --allow-empty-summary 显式豁免。');
+    process.exit(1);
+  }
   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',
+  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> 载荷）');
+    path.join(dir, 'final.data.json'));
   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(' '));
@@ -496,6 +658,26 @@ function exportFinal(result, dir, state, kept, opts = {}) {
   lines.push('  ]', '}');
   // 供 todo-serve.cjs 读取的同构数据（只有三键，无外框）：服务与载荷永远读同一份，不会出现两份数据。
   fs.writeFileSync(path.join(dir, 'final.data.json'), JSON.stringify(payload));
+  // 交付文件（2026-11-01 用户拍板）：由**脚本**按「认证用户名_YYYYmmddHHMMSS.json」落到 ~/Downloads/，
+  // 执行方默认不展示该文件（正文只有组件块）——仅当用户明确要求输出 json 时才交付。
+  // 用户名 = auth whoami → hrm.employee.detail.username，state 缓存免重复查询；失败则不生成并在输出里说明。
+  let deliveredFile = null;
+  const username = resolveDeliverUsername(state, dir);
+  if (username) {
+    try {
+      const d = new Date();
+      const pad = (n) => String(n).padStart(2, '0');
+      const stamp = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+      const downloads = path.join(os.homedir(), 'Downloads');
+      fs.mkdirSync(downloads, { recursive: true });
+      deliveredFile = path.join(downloads, `${username}_${stamp}.json`);
+      fs.writeFileSync(deliveredFile, JSON.stringify(payload));
+    } catch {
+      deliveredFile = null;
+    }
+  }
+  if (deliveredFile) console.log('已生成备用文件：%s（默认不展示；仅当用户明确要求输出 json 时再交付——交付口径以 references §6.1 顶部为准）', deliveredFile);
+  else console.log('备用文件未生成（用户名查询失败或 Downloads 不可写）：如用户要求输出 json，把 %s 复制为 ~/Downloads/<用户名>_<YYYYmmddHHMMSS>.json 后交付', path.join(dir, 'final.data.json'));
   // 数据源模式：`--data-source <url>` 直接用给定地址；`--serve [端口]` 现起一个本地服务拿地址。
   let dataSourceUrl = opts.dataSource && opts.dataSource !== true ? String(opts.dataSource) : null;
   if (!dataSourceUrl && opts.serve) dataSourceUrl = publishSnapshot(dir, opts.serve);
@@ -505,9 +687,8 @@ function exportFinal(result, dir, state, kept, opts = {}) {
     console.log('\n数据源模式：params.dataSource = %s', dataSourceUrl);
     console.log('  组件改为 GET 该地址（响应体就是 params.data 的三键对象）；单进程多快照，快照空闲 30 分钟后自动清理');
   }
-  // 用户 2026-10-27 定稿：交付 = 回复里内联 <browsertool> 整块，**不再生成 JSON 文件**。
-  // `--file` 仅保留作调试（写一份纯载荷 JSON），交付流程不再使用它。
-  if (opts.writeFile) fs.writeFileSync(finalFile, finalText);
+  // 交付 = 回复里内联 <browsertool> 整块 + 另存 final.data.json（Agent 复制它按 §6.1 命名交付）。
+  // 旧 `--file` 分支已删（2026-11-01）：它写的 `待办汇总-*.json` 是外框归档，命名/内容均为旧口径，易误当交付物。
   const delivery = `<browsertool>\n${finalText.trimEnd()}\n</browsertool>`;
   console.log('\n[JSON_BEGIN]');
   console.log(delivery);
@@ -525,7 +706,6 @@ function exportFinal(result, dir, state, kept, opts = {}) {
     console.log('\n耗时摘要（仅 CLI 执行链路，不含模型往返）：');
     console.log(conclusion);
   }
-  return opts.writeFile ? finalFile : null;
 }
 
 /**
@@ -657,12 +837,44 @@ function cmdPrep(args) {
     fmt(collectMs), fmt(collectWallMs));
   console.log('输出目录：%s\n', dir);
   const focusKinds = focusCoversKinds(args.focus && args.focus !== true ? args.focus : '');
+  // 规则里 focus:false 的组**必须**由模型给 aiGroups（如 安全问题处理工单），prep 阶段就标出来，
+  // 不要等 build 报 ai_groups_required 才知道（2026-11-01 用户确认的规范缺陷）。
+  // 同时**回显该组的 groupingPrompt（组名词表/分法）与 requestSummaryPrompt（摘要模板）**——
+  // 这两样只存在于 aigroup/default.json，规则要求"生成 aiGroups 前必须先读它"，
+  // 但 prep 原本不输出 ⇒ 执行方只能凭正文推断（自造组名/漏摘要要素的根因，2026-11-01 复盘定稿）。
+  const mustPlanRules = [];
+  try {
+    const ruleFile = JSON.parse(fs.readFileSync(path.join(path.resolve(__dirname, '..'), 'aigroup', 'default.json'), 'utf8'));
+    for (const rule of ruleFile.rules || []) {
+      if (rule.aiGroup && rule.aiGroup.groupRule && rule.aiGroup.groupRule.focus === false) {
+        const names = Array.isArray(rule.workflowName) ? rule.workflowName : [rule.workflowName];
+        for (const name of names) {
+          if (name && name !== '*') {
+            mustPlanRules.push({
+              name: String(name),
+              groupingPrompt: String((rule.aiGroup.groupRule || {}).groupingPrompt || ''),
+              requestSummaryPrompt: String(rule.requestSummaryPrompt || ''),
+            });
+          }
+        }
+      }
+    }
+  } catch { /* 规则文件读不到就不标注（build 仍会硬校验兜底） */ }
+  const matchRule = (title) => mustPlanRules.find((r) => title.includes(r.name) || r.name.includes(title));
+  const needsPlan = (title, count) => count >= 3 && (title.includes('内部留言') || Boolean(matchRule(title)));
   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 ? ' [无需分组]' : ''}`);
+    const rule = skip ? null : matchRule(group.title);
+    const marker = skip ? ' [无需分组]' : (rule || group.title.includes('内部留言') ? ' [必须给 plan]' : '');
+    console.log(`=== ${group.groupId} | ${group.title} | ${group.count}${marker}`);
     if (skip) continue;
+    // 回显规则内容：组名/分法只按 groupingPrompt 来（词表不得自造），摘要按 requestSummaryPrompt 写
+    if (rule) {
+      if (rule.groupingPrompt) console.log(`    ▸ 分组口径（groupingPrompt，组名/分法只按它来，不得自造）：${rule.groupingPrompt}`);
+      if (rule.requestSummaryPrompt) console.log(`    ▸ 摘要模板（requestSummaryPrompt，本组单条摘要照它写）：${rule.requestSummaryPrompt}`);
+    }
     for (const row of group.rows) {
       const hint = fieldHintById.get(row.requestId) || '';
       // 提示放在**同一行**：两行格式容易让人（和模型）回头去匹配标题，而标题里往往没有类型词。
@@ -670,7 +882,7 @@ function cmdPrep(args) {
     }
   }
   console.log('\n下一步：node %s build --dir %s', path.basename(__filename), dir);
-  console.log('（只有内部留言组、或用户给了侧重点时才需要再补 --plan <aiGroups.json>；其余走确定性分组）');
+  console.log('（标了 [必须给 plan] 的组——内部留言、以及规则 focus:false 的组如 安全问题处理工单——build 时必须带 --plan <aiGroups.json>；组名/分法/摘要口径见各组下回显的规则内容；其余走确定性分组）');
 }
 
 function cmdBuild(args) {
@@ -680,7 +892,7 @@ function cmdBuild(args) {
   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 计划。
+  // `--plan`：确定性类型可不传；prep 标了 [必须给 plan] 的组（内部留言 / focus:false 组）不传会被 CLI 拒（ai_groups_required）。
   // 不传时直接走 CLI 确定性分组（等价于 aiGroups 未传）。
   let aiGroups;
   if (planFile) {
@@ -742,17 +954,39 @@ function cmdBuild(args) {
   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'] });
+    // 即使无待写摘要也必须走 finish：summary 阶段还负责满意度类（needSummary:false）的标题
+    // 填充与交付闸门——smartGroup 半成品直接导出会让这类条目空着（2026-11-01 闸门真机首跑抓到）。
+    cmdFinish({ ...args, dir });
     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待写摘要（把结果写成 aiSummaries.json，元素 {requestId,summary}；每批的「口径」必须遵守）：`);
+  for (const b of batches) {
+    const items = b.items || [];
+    if (items.length === 0) continue;
+    console.log(`## 批次 ${b.batchId}｜${b.groupTitle}${b.subGroupTitle && b.subGroupTitle !== b.groupTitle ? ` → ${b.subGroupTitle}` : ''}｜目标字数 ${b.suggestedMaxChars}`);
+    if (b.prompt) console.log(`口径：${b.prompt}`);
+    if (b.hint) console.log(`提示：${b.hint}`);
+    for (const item of items) {
+      console.log(`### ${item.requestId}`);
+      console.log(`T: ${String(item.requestNameTitle || '').slice(0, 160)}`);
+      // 素材**几乎不截断**（4000 字符保险丝）：2026-11-01 实测 240 字截断把 e-todo 模板的
+      // 「预估开发总人天/需求概述」等尾部要素裁掉，模型只能靠标题凑数（要素缺失复盘定稿）。
+      console.log(`C: ${String(item.context || '').replace(/\s+/g, ' ').slice(0, 4000)}`);
+    }
   }
   console.log('\n下一步：node %s finish --dir %s --summaries <aiSummaries.json>', path.basename(__filename), dir);
+  // 组摘要（aiGroup.groupSummary.needAI=true 的汇总项）：口径随批次下发，模型按它写 aiGroupSummaries
+  const gsBatches = sg.data.groupSummaryBatches || [];
+  if (gsBatches.length > 0) {
+    console.log('\n待写组摘要（写成 aiGroupSummaries.json，元素 {groupId,summary}）：');
+    for (const b of gsBatches) {
+      console.log(`### 组摘要 ${b.groupId}｜${b.parentTitle} → ${b.title}｜${b.count} 条｜目标字数 ${b.suggestedMaxChars}`);
+      if (b.prompt) console.log(`口径：${b.prompt}`);
+      if (b.hint) console.log(`提示：${b.hint}`);
+      if (b.stats && b.stats.tail) console.log(`tail：${b.stats.tail}`);
+    }
+    console.log('\nfinish 时加：--group-summaries <aiGroupSummaries.json>');
+  }
 }
 
 function cmdFinish(args) {
@@ -788,6 +1022,9 @@ function cmdFinish(args) {
   fs.writeFileSync(path.join(dir, 'state.json'), JSON.stringify(state));
   console.log('summary 内部 %s / 含进程启动 %s（回填 %d 条，其余走缓存预填）',
     summaryInternal === null ? '-' : fmt(summaryInternal), fmt(summaryWallMs), aiSummaries.length);
+  // 未回填的缺失 id 不在这里单列：summary 阶段的信封不带 summaryBatches/summaryStats，
+  // 空 id 列表统一由 exportFinal 的闸门①从最终结构里就地提取（能直接给出 requestId）。
+  // 未知 requestId 的 aiSummaries 由 CLI 侧硬校验拒绝（ai_summary_unknown_request，非零退出）。
   let finalResult = result;
   const groupBatches = result.data.groupSummaryBatches || [];
   if (groupBatches.length > 0) {
@@ -819,6 +1056,10 @@ function cmdFinish(args) {
       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>` 重跑本命令，可在同一次调用里回填');
+      if (args['allow-empty-summary'] !== true) {
+        console.error('✖ 交付拦截：%d 个组摘要未回填，导出会是空组摘要。补齐 --group-summaries 后重跑，或加 --allow-empty-summary 显式豁免。', groupBatches.length);
+        process.exit(1);
+      }
     }
   }
   // 2026-10-28 用户 OA 页面实测通过：默认走本地数据源（params.dataSource），
@@ -827,10 +1068,15 @@ function cmdFinish(args) {
     ? false
     : (args.serve === undefined ? true : args.serve);
   exportFinal(finalResult, dir, state, kept.length, {
-    writeFile: args.file === true,
     timingReport: args['timing-report'],
     dataSource: args['data-source'],
     serve: serveOption,
+    // 交付硬闸门（2026-11-01）：空摘要 / 详情取数失败都要显式豁免才能出文件。
+    // 详情取数发生在 smartGroup 阶段 ⇒ failed 从 smartgroup.json 的 data.summaryStats 取。
+    allowEmptySummary: args['allow-empty-summary'] === true,
+    allowDetailFail: args['allow-detail-fail'] === true,
+    detailFailed: ((sg.data || {}).summaryStats || {}).failed || 0,
+    groupEmpty: (finalResult.meta && finalResult.meta.groupEmpty) || 0,
   });
   console.log('总耗时（脚本口径）：%s', fmt(Date.now() - Date.parse(state.startedAt)));
 }
@@ -849,21 +1095,24 @@ function cmdRun(args) {
     : `/tmp/todo-summary-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}`;
   cmdPrep({ ...args, out: dir });
   cmdBuild({ ...args, dir });
+  // 无待写摘要时 cmdBuild 已经内部走完 cmdFinish（含满意度标题填充与交付闸门），这里直接收工
+  if (fs.existsSync(path.join(dir, 'final.data.json'))) return;
   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);
+    console.log('  node %s finish --dir %s --summaries <aiSummaries.json> --timing-report', path.basename(__filename), dir);
     return;
   }
-  // 没有待写摘要 ⇒ 终态可以立刻出，省掉一次约 7s 的进程启动
+  // build 停下但没导出（如组摘要待回填）⇒ 把 finish 跑完（它自己会按闸门决定放行/拦截）
   cmdFinish({
     dir,
-    file: args.file === true,
     'timing-report': args['timing-report'],
     'group-summaries': args['group-summaries'],
     serve: args.serve,
     'no-serve': args['no-serve'],
+    'allow-empty-summary': args['allow-empty-summary'] === true,
+    'allow-detail-fail': args['allow-detail-fail'] === true,
   });
 }
 
@@ -875,10 +1124,11 @@ 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('  run    [--days N | --from A --to B] [--limit 500] [--out DIR] [--timing-report]   # 一次跑完 prep+build；用户没说时间段就都不传 = 不限时间取前 500 条');
   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('  build  --dir DIR [--plan aiGroups.json]   # prep 标注 [必须给 plan] 的组必须传；其余不传走确定性分组');
+  console.log('  finish --dir DIR [--summaries aiSummaries.json] [--group-summaries aiGroupSummaries.json] [--timing-report]');
+  console.log('  交付闸门：空摘要 / 组摘要缺失 / 详情取数失败都会 exit 1 拒绝导出；显式豁免：--allow-empty-summary / --allow-detail-fail');
   console.log('  默认：载荷只带 params.dataSource（现起本地服务，空闲 30 分钟自动退出）；--no-serve 退回内联 data');
   console.log('  提示：`--timing-report` 会在控制台打一段耗时摘要（阶段墙钟 / CLI 内部），**不产出 md**');
   process.exit(2);