weaver-work-cli 0.1.28 → 0.1.29

package/dist/shortcuts/workflow/operations/todoSmartConvert/todoSmartConvert.collect.js

@@ -0,0 +1,267 @@
+import { WORKFLOW_ENDPOINTS } from '../../endpoints.js';
+import { saveSearchIndex } from '../../state.js';
+import { buildSearchQuery } from '../read.js';
+import { projectDisplayRows } from './todoListRows.js';
+import { responseData } from '../shared.js';
+import { openSummaryCache, SUMMARY_CACHE_FILE_NAME } from './summaryCache.js';
+import { detectBusinessKind } from './businessRules.js';
+import { fetchDetailFacts, stampsOfRows } from './todoSmartConvert.detail.js';
+import { focusAppliesToKind, GROUP_MIN_ITEMS_FOR_SUBGROUP, isExpiringTodayRow, isOverdueRow, runGroup, } from './todoSmartConvert.group.js';
+import { DEFAULT_TABID, FETCH_PAGE_SIZE, LIST_ENDPOINT_BY_CATEGORY, MAX_FETCH_LIMIT, MAX_FETCH_PAGES, guardListOnlyHost, readBoundedInt, readCategory, readFetchLimit, readPageSize, rowFromAny, } from './todoSmartConvert.core.js';
+const DEFAULT_REQUEST_SUMMARY_MAX = 50;
+export async function collectRawTodos(args, env) {
+    const category = readCategory(args.category);
+    const { limit, cappedFrom } = readFetchLimit(args.limit);
+    const pageSize = readPageSize(limit);
+    // 条数 → 请求次数；按页取，不按条数精确裁剪。
+    const plannedPages = Math.max(1, Math.min(Math.ceil(limit / pageSize), MAX_FETCH_PAGES));
+    // 取数阶段只允许 getTodoListData，getTodo* 分页/统计接口一律拦掉。
+    const listEnv = guardListOnlyHost(env);
+    const searchArgs = { category };
+    for (const key of ['tabid', 'tabName', 'subCategory', 'workflow', 'creator', 'requestName', 'receiveTime', 'requestLevel']) {
+        const value = args[key];
+        if (value !== undefined && value !== null && value !== '')
+            searchArgs[key] = value;
+    }
+    // 显式给 tabid 才走平铺路径（见 DEFAULT_TABID 注释）；用户另有子分类条件时原样尊重。
+    const explicitTab = ['tabid', 'tabName', 'subCategory'].some((key) => searchArgs[key] !== undefined && String(searchArgs[key]).trim() !== '');
+    if (!explicitTab)
+        searchArgs.tabid = DEFAULT_TABID;
+    const warnings = [];
+    if (cappedFrom !== undefined) {
+        // 超过上限时显式告知，避免调用方误以为已取全量。
+        warnings.push(`单次最多只能取 ${MAX_FETCH_LIMIT} 条（${MAX_FETCH_PAGES} 次请求 × ${FETCH_PAGE_SIZE} 条），`
+            + `你要求的 ${cappedFrom} 条已按上限 ${MAX_FETCH_LIMIT} 条处理；`
+            + '如需覆盖更多，请缩小筛选条件（如按工作流、时间范围分批）后再汇总');
+    }
+    const requestedPageSize = args.pageSize;
+    if (requestedPageSize !== undefined && requestedPageSize !== null && requestedPageSize !== ''
+        && Number(requestedPageSize) !== pageSize) {
+        warnings.push(`单页条数已按 limit 推导为 ${pageSize}（最多 ${MAX_FETCH_PAGES} 次请求），`
+            + `忽略传入的 pageSize=${String(requestedPageSize)}`);
+    }
+    const seen = new Set();
+    const items = [];
+    let duplicateCount = 0;
+    let totalAvailable = null;
+    let pages = 0;
+    let stoppedEarly = false;
+    const listPath = LIST_ENDPOINT_BY_CATEGORY[category] ?? WORKFLOW_ENDPOINTS.TODO_LIST;
+    for (let pageNo = 1; pageNo <= plannedPages; pageNo += 1) {
+        const { query } = await buildSearchQuery(listEnv, { ...searchArgs, current: pageNo, pageSize }, 'list');
+        const response = await listEnv.host.workflowRequest({
+            method: 'POST',
+            path: listPath,
+            operation: 'workflow.todoSmartConvert.list',
+            body: query,
+        });
+        pages += 1;
+        if (totalAvailable === null) {
+            // 列表接口的 total 字段不稳定（实测 `data.total` 可能是 0 或缺失）。取数按页驱动、不依赖总数，
+            // 所以这里**只做展示用**：拿不到正数就当未知，不让 0 冒充「共 0 条」。
+            const record = responseData(response);
+            const candidates = [record?.data?.total, record?.data?.totalCount, record?.total, record?.totalCount];
+            for (const candidate of candidates) {
+                const total = Number(candidate);
+                if (Number.isFinite(total) && total > 0) {
+                    totalAvailable = total;
+                    break;
+                }
+            }
+        }
+        const pageRows = projectDisplayRows(response)
+            .map((row) => rowFromAny(row))
+            .filter((row) => row !== undefined);
+        if (pageRows.length === 0) {
+            stoppedEarly = true;
+            break;
+        }
+        let added = 0;
+        for (const row of pageRows) {
+            if (row.requestId) {
+                if (seen.has(row.requestId)) {
+                    duplicateCount += 1;
+                    continue;
+                }
+                seen.add(row.requestId);
+            }
+            items.push(row);
+            added += 1;
+        }
+        if (added === 0)
+            break;
+        // 累计到目标条数即停：`limit` 是阈值，不是「最多取一页」。
+        if (items.length >= limit)
+            break;
+        // 这一页不满 pageSize ⇒ 已经没有下一页，不必再请求。
+        if (pageRows.length < pageSize)
+            break;
+    }
+    // 刷新本地查询快照（本地写文件，不联网）：批量写门禁以「最近一次查询结果」为准，
+    // 不写会让 todoSmartConvert 取到的 ID 在 workflow.batch* 那里被判成「不在快照里」。
+    await saveSearchIndex({
+        items: items.map((row, index) => ({
+            index: index + 1,
+            requestId: row.requestId,
+            requestName: row.requestNameTitle,
+            workflowId: row.workflowId,
+            workflowName: row.workflowName,
+            creator: row.createrName,
+            userMasterId: row.userMasterId,
+            isremark: row.isremark,
+            isRemark: row.isremark,
+            nodeid: row.nodeId,
+            nodeId: row.nodeId,
+            cardSummary: row.summary,
+        })),
+        summary: { type: 'todoSmartConvert', category, total: totalAvailable, pages },
+    }, env.ctx).catch(() => undefined);
+    if (duplicateCount > 0) {
+        warnings.push(`跨页重复 ${duplicateCount} 条，已按 requestId 去重`);
+    }
+    if (stoppedEarly && items.length === 0) {
+        warnings.push('列表接口没有返回任何明细，请确认筛选条件是否过窄');
+    }
+    if (totalAvailable !== null && items.length < totalAvailable) {
+        warnings.push(`共 ${totalAvailable} 条待办，本次按 ${pages} 次请求（每次最多 ${FETCH_PAGE_SIZE} 条）取到 ${items.length} 条；`
+            + `已到本次 limit=${limit} 的阈值——`
+            + '需要覆盖更多请调大 limit，或缩小筛选条件（工作流 / 时间范围）分批汇总');
+    }
+    const scope = searchArgs.tabid ? `tabid ${searchArgs.tabid}` : '';
+    const header = `已获取待办原始数据 ${items.length} 条`
+        + (totalAvailable !== null ? `（共 ${totalAvailable} 条）` : '');
+    // collect 同时生成第一次分组，并只读取摘要缓存；详情在后续阶段按需获取。
+    let wfIdGroup = [];
+    let groupingBrief = [];
+    let groupInfo = null;
+    let detailStats = null;
+    if (items.length > 0) {
+        const grouped = runGroup({
+            items,
+            ...(args.groupBy !== undefined ? { groupBy: args.groupBy } : {}),
+            ...(args.topN !== undefined ? { topN: args.topN } : {}),
+        });
+        wfIdGroup = (grouped.wfIdGroup ?? []);
+        // 摘要缓存 key 为 requestId 与最后反馈时间；反馈变化会自然失效。
+        const summaryCache = await openSummaryCache(env.ctx);
+        // 调用方指定摘要字数时不能命中其他字数口径的旧条目。
+        const collectSummaryMaxChars = readBoundedInt(args.summaryMaxChars, "summaryMaxChars", DEFAULT_REQUEST_SUMMARY_MAX, 10, 500);
+        const cachedSummaryIds = new Set();
+        for (const row of items) {
+            const cached = summaryCache.get(row.requestId, row.lastFeedBackDateTime, collectSummaryMaxChars);
+            if (!cached)
+                continue;
+            row.summary = cached;
+            cachedSummaryIds.add(row.requestId);
+        }
+        // 详情是流水线中间数据，smartGroup / summaryContext 需要时现场拉取（带缓存）。
+        // 例外：**有意图时**，ai二次分组要先看到表单字段，这里就把素材准备好（见下）。
+        detailStats = {
+            deferred: true,
+            note: '详情不预取：smartGroup / summaryContext 会在需要时现场拉取（详情缓存优先）',
+            summaryCached: cachedSummaryIds.size,
+            summaryCacheFile: summaryCache.file,
+            summaryCachePruned: summaryCache.pruned,
+        };
+        // 有意图时把**流程详情数据**作为 ai二次分组素材交给模型。
+        // 范围按意图表判定（专属意图只作用于请假/财务/问题支持，通用意图只作用于内部留言/其他），
+        // 走详情缓存（键 `requestId__lastFeedBackDateTime`），与后续摘要阶段共用同一份数据。
+        const focusText = typeof args.groupFocus === 'string' ? args.groupFocus.trim() : '';
+        const fieldsById = new Map();
+        if (focusText) {
+            const targetRows = wfIdGroup
+                .filter((group) => !group.topPriority && focusAppliesToKind(focusText, detectBusinessKind(group.title)))
+                .flatMap((group) => group.requestDatas ?? []);
+            const targetIds = [...new Set(targetRows.map((row) => row.requestId).filter(Boolean))];
+            if (targetIds.length > 0) {
+                const { facts, stats } = await fetchDetailFacts(env, targetIds, args, stampsOfRows(targetRows));
+                for (const [requestId, fact] of facts) {
+                    if (fact.fields.length > 0)
+                        fieldsById.set(requestId, fact.fields);
+                }
+                detailStats.groupingMaterial = {
+                    requested: targetIds.length,
+                    cacheHit: stats.cacheHit,
+                    fetched: stats.fetched,
+                    failed: stats.failed,
+                    withFields: fieldsById.size,
+                };
+            }
+        }
+        // 给模型的紧凑视图使用组内序号，aiGroups 可用 seq 引用。
+        groupingBrief = wfIdGroup.map((group) => ({
+            groupId: group.id,
+            title: group.title,
+            count: group.count,
+            topPriority: group.topPriority,
+            items: (group.requestDatas ?? []).map((row, index) => ({
+                idx: index + 1,
+                requestId: row.requestId,
+                title: row.requestNameTitle ?? '',
+                // 客户问题支持类无侧重点时按这两个布尔分组（模型不用自己解析日期文案）
+                overdue: isOverdueRow(row),
+                expiringToday: isExpiringTodayRow(row),
+                ...(row.userOverTime ? { userOverTime: row.userOverTime } : {}),
+                ...(row.summary ? { summary: row.summary } : {}),
+                // `summaryCached:true` = 这条已有本地摘要（按 requestId__lastFeedBackDateTime 命中），
+                // 分组仍要做（聚类看标题），但**不要再给它写摘要**。
+                ...(cachedSummaryIds.has(row.requestId) ? { summaryCached: true } : {}),
+                ...(fieldsById.has(row.requestId) ? { fields: fieldsById.get(row.requestId) } : {}),
+            })),
+        }));
+        // 用户侧重点原样回显：分组/排序都按「标题语义 + 侧重点」，模型照它决定子组与顺序。
+        const groupingFocus = typeof args.groupFocus === 'string' ? args.groupFocus.trim() : '';
+        groupInfo = {
+            smartSummaryTitle: grouped.smartSummaryTitle,
+            groupBy: grouped.groupBy,
+            groupCount: grouped.groupCount,
+            total: grouped.total,
+            totals: grouped.totals,
+            restTotal: grouped.restTotal,
+            restGroupCount: grouped.restGroupCount,
+            warnings: grouped.warnings,
+            ...(groupingFocus ? { groupFocus: groupingFocus } : {}),
+            // 二次分组门槛：组内少于 3 条直接单条展示。
+            minItemsForSubgroup: GROUP_MIN_ITEMS_FOR_SUBGROUP,
+        };
+        if (cachedSummaryIds.size > 0) {
+            warnings.push(`有 ${cachedSummaryIds.size} 条命中本地摘要缓存（key=requestId__lastFeedBackDateTime），`
+                + '这些条目**不用再写摘要**，summary 已从缓存回填；本次也不会为它们发详情请求'
+                + `（缓存文件：${summaryCache.file ?? SUMMARY_CACHE_FILE_NAME}）`);
+        }
+        if (!summaryCache.inSkillDir) {
+            warnings.push('没有找到本机 Agent 的 weaver-e10-workflow skill 目录，摘要缓存已退回 CLI 状态目录；'
+                + '如需缓存落在 skill 目录，可用 WEAVER_WORK_CLI_SKILL_DIR 指定');
+        }
+    }
+    return {
+        stage: 'collect',
+        query: {
+            category,
+            ...(scope ? { tabid: searchArgs.tabid } : {}),
+            /** 用户原始诉求；超过上限时保留原值，实际按上限取。 */
+            requestedLimit: cappedFrom ?? limit,
+            /** 计划请求次数（最多 5 页）。 */
+            plannedPages,
+            /** 实际发出的列表请求次数 */
+            pages,
+            /** 单页大小（limit ≤ 100 时等于 limit，否则固定 100） */
+            pageSize,
+            /** 计划能覆盖的条数上限 = 计划页数 × 单页（实际可能更少，取决于服务端还有没有数据） */
+            appliedLimit: plannedPages * pageSize,
+            totalAvailable,
+            /** 取数只用了这一个接口（照实写出来，便于核对「有没有偷偷调别的」） */
+            endpoint: listPath,
+            filters: Object.fromEntries(Object.entries(searchArgs).filter(([key]) => !['category', 'tabid'].includes(key))),
+        },
+        fetched: items.length,
+        items,
+        wfIdGroup,
+        groupingBrief,
+        groupInfo,
+        /** 详情状态；详情由后续阶段按需获取。 */
+        detailStats,
+        warnings,
+        markdown: header,
+    };
+}

package/dist/shortcuts/workflow/operations/todoSmartConvert/todoSmartConvert.core.js

@@ -0,0 +1,392 @@
+import { workflowValidationError } from '../../errors.js';
+import { WORKFLOW_ENDPOINTS } from '../../endpoints.js';
+import { workflowSuccess as envelopeSuccess } from '../types.js';
+export const GROUP_BY_VALUES = ['workflow', 'urgency', 'date', 'none'];
+export const UNKNOWN_GROUP = '未分类';
+export const UNKNOWN_DATE = '未知日期';
+export const DEFAULT_TOP_N = 10;
+export const STAGE_VALUES = [
+    'auto', 'collect', 'group', 'smartGroup',
+    'summaryContext', 'summary', 'groupSummaryContext', 'groupSummary',
+    'aggregate',
+];
+export function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+/** 统一去重告警，并同时写入 meta 与兼容的信封级字段。 */
+export function workflowSuccess(action, data, meta, warnings) {
+    const list = [...new Set((warnings ?? []).filter((item) => typeof item === 'string' && item.trim() !== ''))];
+    const mergedMeta = list.length > 0 ? { ...(meta ?? {}), warnings: list } : meta;
+    const base = envelopeSuccess(action, data, mergedMeta);
+    return (list.length > 0 ? { ...base, warnings: list } : base);
+}
+/** 跨 CLI 回灌累计耗时；AI 耗时由 skill 在模型调用前后测量后传入。 */
+export function buildSkillTiming(stage, input, startedAt) {
+    const value = input && typeof input === 'object' ? input : {};
+    const previous = Array.isArray(value.steps)
+        ? value.steps.filter((step) => step && typeof step.name === 'string'
+            && (step.kind === 'cli' || step.kind === 'ai' || step.kind === 'stage')
+            && Number.isFinite(step.durationMs) && step.durationMs >= 0)
+            .map((step) => ({ name: step.name, kind: step.kind, durationMs: Math.round(step.durationMs) }))
+        : [];
+    const cliDurationMs = Math.max(0, Date.now() - startedAt);
+    const aiDurationMs = Number.isFinite(value.aiDurationMs) && (value.aiDurationMs ?? 0) >= 0
+        ? Math.round(value.aiDurationMs)
+        : 0;
+    const steps = [
+        ...previous,
+        ...(aiDurationMs > 0 ? [{ name: stage, kind: 'ai', durationMs: aiDurationMs }] : []),
+        { name: stage, kind: 'cli', durationMs: cliDurationMs },
+    ];
+    const measuredSum = steps.reduce((sum, step) => sum + step.durationMs, 0);
+    const wallElapsedMs = typeof value.startedAt === 'string' ? Date.now() - Date.parse(value.startedAt) : NaN;
+    return {
+        startedAt: typeof value.startedAt === 'string' ? value.startedAt : new Date(startedAt).toISOString(),
+        finishedAt: new Date().toISOString(),
+        stage,
+        steps,
+        durationMs: Math.max(measuredSum, Number.isFinite(wallElapsedMs) && wallElapsedMs >= 0 ? wallElapsedMs : 0),
+    };
+}
+/** 金额可能是 "1,234.50"、"¥1234"、数字或空；只保留数字与小数点后重试，失败按「缺金额」处理。 */
+function parseAmount(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string')
+        return undefined;
+    const cleaned = value.replace(/[^\d.-]/gu, '');
+    if (!cleaned || cleaned === '-' || cleaned === '.')
+        return undefined;
+    const parsed = Number(cleaned);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function toDateKey(date) {
+    if (Number.isNaN(date.getTime()))
+        return UNKNOWN_DATE;
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/** 时间表示不唯一：毫秒/秒时间戳、`YYYY-MM-DD`、`YYYY/MM/DD`；识别不了归「未知日期」，不猜。 */
+function dateBucket(value) {
+    if (!value)
+        return UNKNOWN_DATE;
+    const text = value.trim();
+    if (/^\d{13}$/u.test(text))
+        return toDateKey(new Date(Number(text)));
+    if (/^\d{10}$/u.test(text))
+        return toDateKey(new Date(Number(text) * 1000));
+    const matched = text.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})/u);
+    if (matched) {
+        const [, year, month, day] = matched;
+        return `${year}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`;
+    }
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? UNKNOWN_DATE : toDateKey(parsed);
+}
+export function readGroupBy(value) {
+    if (value === undefined || value === null || value === '')
+        return 'workflow';
+    const text = String(value);
+    if (GROUP_BY_VALUES.includes(text))
+        return text;
+    throw workflowValidationError('group_by_invalid', `groupBy 只支持 ${GROUP_BY_VALUES.join(' / ')}，收到 ${text}`, { retryAllowed: false, details: { allowed: GROUP_BY_VALUES } });
+}
+export function readTopN(value) {
+    if (value === undefined || value === null || value === '')
+        return DEFAULT_TOP_N;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 50) {
+        throw workflowValidationError('top_n_invalid', `topN 必须是 1~50 的整数，收到 ${String(value)}`);
+    }
+    return parsed;
+}
+export function renderMarkdown(params) {
+    const { groupBy, total, groups, restGroupCount, restCount, hasAmount } = params;
+    const dimension = {
+        workflow: '按工作流',
+        urgency: '按紧急程度',
+        date: '按接收日期',
+        none: '不分组',
+    };
+    const lines = [
+        `待办汇总（${dimension[groupBy]}，共 ${total} 条，${groups.length + restGroupCount} 组）`,
+        '',
+        hasAmount ? '| 分组 | 条数 | 金额合计 |' : '| 分组 | 条数 |',
+        hasAmount ? '| --- | --- | --- |' : '| --- | --- |',
+    ];
+    for (const group of groups) {
+        if (!hasAmount) {
+            lines.push(`| ${group.key} | ${group.count} |`);
+            continue;
+        }
+        const amountCell = group.amountCount === 0 ? '—' : group.amountSum.toFixed(2);
+        lines.push(`| ${group.key} | ${group.count} | ${amountCell} |`);
+    }
+    if (restGroupCount > 0) {
+        lines.push(`| 其余 ${restGroupCount} 组 | ${restCount} |${hasAmount ? ' — |' : ''}`);
+    }
+    return lines.join('\n');
+}
+export const ALLOWED_INPUT_KEYS = [
+    'stage',
+    'items',
+    'aiGroups',
+    'aiSummaries',
+    'aiGroupSummaries',
+    'withDetailContext',
+    'withGroupSummaryContext',
+    'detailPrefetch',
+    'maxCharsPerBatch',
+    'maxItemsPerBatch',
+    'summaryMaxChars',
+    'groupSummaryMaxChars',
+    'groupFocus',
+    'detailConcurrency',
+    'detailTimeoutMs',
+    'groupBy',
+    'groupOrder',
+    'topN',
+    'limit',
+    'pageSize',
+    'category',
+    'tabid',
+    'tabName',
+    'subCategory',
+    'workflow',
+    'creator',
+    'requestName',
+    'receiveTime',
+    'requestLevel',
+    'skillTiming',
+];
+/** 允许把上一阶段的 data 原样回灌到下一阶段。 */
+export const RESUME_INPUT_KEYS = [
+    'query', 'fetched', 'warnings', 'markdown',
+    'smartSummaryTitle', 'totalCount', 'wfIdGroup', 'summaryBatches', 'summaryStats',
+    'groupSummaryBatches', 'groupSummaryStats', 'groupInfo', 'groupingBrief', 'detailStats',
+    'skillTiming',
+    'smartSmmaryTitle',
+];
+/** collect 的分页上限与默认值。按 current 递增翻页。 */
+export const DEFAULT_FETCH_LIMIT = 200;
+/** 与下游 `readItems` 的 items 上限（500）对齐：一次汇总最多吃 500 条。 */
+export const MAX_FETCH_LIMIT = 500;
+/** 列表接口单页上限。 */
+export const FETCH_PAGE_SIZE = 100;
+/** 安全上限：最多 5 次请求（`current` 1..5），覆盖 500 条。 */
+export const MAX_FETCH_PAGES = 5;
+/** 分类 → 列表接口。collect 只使用列表接口，不调总数或详情接口。 */
+export const LIST_ENDPOINT_BY_CATEGORY = {
+    todo: WORKFLOW_ENDPOINTS.TODO_LIST,
+    done: WORKFLOW_ENDPOINTS.DONE_LIST,
+    mine: WORKFLOW_ENDPOINTS.MINE_LIST,
+    all: WORKFLOW_ENDPOINTS.ALL_LIST,
+};
+export const DEFAULT_CATEGORY = 'todo';
+/** 默认「全部待办」使用 tabid 0，确保列表接口返回平铺数据。 */
+export const DEFAULT_TABID = '0';
+export const CATEGORY_VALUES = ['todo', 'done', 'mine', 'all'];
+export function readFetchLimit(value) {
+    if (value === undefined || value === null || value === '')
+        return { limit: DEFAULT_FETCH_LIMIT };
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw workflowValidationError('limit_invalid', `limit 必须是 ≥1 的整数，收到 ${String(value)}`);
+    }
+    if (parsed > MAX_FETCH_LIMIT)
+        return { limit: MAX_FETCH_LIMIT, cappedFrom: parsed };
+    return { limit: parsed };
+}
+export function readCategory(value) {
+    if (value === undefined || value === null || value === '')
+        return DEFAULT_CATEGORY;
+    const text = String(value);
+    if (!CATEGORY_VALUES.includes(text)) {
+        throw workflowValidationError('category_invalid', `category 只支持 ${CATEGORY_VALUES.join(' / ')}，收到 ${text}`, { retryAllowed: false, details: { allowed: CATEGORY_VALUES } });
+    }
+    return text;
+}
+/**
+ * 单页大小：**由 limit 推导，不再接受外部指定**。
+ *
+ *  - `limit ≤ 100` → 单页就是 limit（用户说 30 条就只请求 30 条，不多拿 70 条）；
+ *  - `limit > 100` → 固定 100，靠 `current` 递增翻页直到累计到 limit（上限 `MAX_FETCH_PAGES` 页）。
+ *
+ * 显式传 `pageSize` 不采用：页大小必须和「累计到 limit 即停」配套，否则同一份 plan 会翻错页。
+ */
+export function readPageSize(limit) {
+    return limit <= FETCH_PAGE_SIZE ? limit : FETCH_PAGE_SIZE;
+}
+/** collect 阶段只允许列表数据接口，避免隐式增加总数或辅助统计请求。 */
+export function guardListOnlyHost(env) {
+    const host = env.host;
+    const wrapped = new Proxy(host, {
+        get(target, prop, receiver) {
+            if (prop === 'workflowRequest') {
+                return async (request) => {
+                    const path = String(request?.path ?? '');
+                    if (/getTodo(?!ListData)/u.test(path)) {
+                        throw workflowValidationError('forbidden_endpoint', `取数阶段只允许调用 getTodoListData；${path} 属于 getTodo* 分页/统计辅助接口，已禁止`, { retryAllowed: false, details: { path } });
+                    }
+                    return target.workflowRequest(request);
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+    return { ...env, host: wrapped };
+}
+/** 去重键：有 requestId 用它，没有就回落「标题 + 接收时间」。 */
+export function rowKeyOf(row) {
+    if (row.requestId)
+        return `id:${row.requestId}`;
+    return `tx:${row.requestNameTitle}|${row.receivedTime ?? ''}`;
+}
+/** 将显示层紧急程度归一为可分组文本。 */
+function urgencyOf(row) {
+    if (row.requestLevelShow)
+        return row.requestLevelShow;
+    return row.requestLevel >= 2 ? '紧急' : UNKNOWN_GROUP;
+}
+/** 分组维度取值。`urgency` 取显示层字段，取不到就进「未分类」，不用占位值凑。 */
+export function groupKeyOf(row, groupBy) {
+    switch (groupBy) {
+        case 'workflow':
+            return row.workflowName || UNKNOWN_GROUP;
+        case 'urgency':
+            return urgencyOf(row);
+        case 'date':
+            return dateBucket(row.receivedTime);
+        case 'none':
+            return '全部待办';
+        default:
+            return UNKNOWN_GROUP;
+    }
+}
+/** displayData 里 `requestlevelShow` 这类列是富文本（`<span style=...>正常</span>`）；
+ *  汇总只要文本，标签与折叠空白一并清掉，避免同一等级在分组时被 HTML 差异拆成两组。 */
+function stripDisplayHtml(value) {
+    return value
+        .replace(/<[^>]*>/gu, ' ')
+        .replace(/&nbsp;/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+/**
+ * 把**任意来源**的一行归一成 `RawTodoRow`：displayData 原始行（snake 键）、取数阶段输出的
+ * items（目标键）、以及历史 `aggregate` 入参（`title`/`creator`/`urgency` 这类旧键）都认。
+ *
+ * 只认显示层字段名，**不回落**技术行字段；取不到就留空/0，不猜。
+ */
+export function rowFromAny(raw) {
+    const record = asRecord(raw);
+    if (!record)
+        return undefined;
+    const pick = (keys, sanitize = false) => {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === 'string' && value.trim()) {
+                const text = sanitize ? stripDisplayHtml(value) : value.trim();
+                if (text)
+                    return text;
+            }
+            if (typeof value === 'number' && Number.isFinite(value))
+                return String(value);
+        }
+        return undefined;
+    };
+    const pickNumber = (keys) => {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === 'number' && Number.isFinite(value))
+                return value;
+            if (typeof value === 'string' && value.trim()) {
+                const parsed = Number(value.trim());
+                if (Number.isFinite(parsed))
+                    return parsed;
+            }
+        }
+        return 0;
+    };
+    return {
+        requestId: pick(['requestId', 'requestid', 'request_id', 'id']) ?? '',
+        workflowId: pick(['workflowId', 'workflowid', 'workflowtype']) ?? '',
+        userMasterId: pick(['userMasterId', 'usermasterid', 'userid']) ?? '',
+        isremark: pickNumber(['isremark', 'isRemark']),
+        nodeId: pick(['nodeId', 'nodeid', 'currentNodeId']) ?? '',
+        overTime: record.overdue === true || record.overTime === true || record.overtime === true,
+        userOverTime: pick(['userOverTime', 'userOvertime', 'userovertime']) ?? '',
+        requestLevel: pickNumber(['requestLevel', 'requestlevel']),
+        // requestlevelTitle 是纯文本（"正常"），requestlevelShow 带 span；两者都清洗后再取。
+        requestLevelShow: pick(['requestlevelTitle', 'requestLevelShow', 'requestlevelShow', 'requestLevelText', 'urgency'], true) ?? '',
+        requestNameTitle: pick(['requestNameTitle', 'requestnameTitle', 'requestnametitle', 'requestname', 'title', 'flowName'], true) ?? '',
+        creater: pick(['creater', 'createrId', 'creatorId']) ?? '',
+        createrName: pick(['createrName', 'creatername', 'creatorName', 'creator']) ?? '',
+        // 最后反馈时间：接口原始键是全小写 `lastfeedbackdatetime`；本模块自己的输出键是
+        // `lastFeedBackDateTime`（大写 B）。**两种拼写都要认**——数据在 CLI 各阶段之间回灌时
+        // 会重新走一遍归一，只认接口拼法会让这个字段在第二阶段悄悄变成空串。
+        lastFeedBackDateTime: pick([
+            'lastFeedBackDateTime', 'lastfeedbackdatetime', 'lastFeedbackDateTime', 'lastfeedbacktime', 'lastFeedbackTime',
+        ]) ?? '',
+        summary: pick(['summary']),
+        workflowName: pick(['workflowName', 'workflowname', 'workflowTypeName'], true),
+        receivedTime: pick(['receivedTime', 'receivedtime', 'receivedatetime', 'operatedatetime', 'stayStartAt']),
+        flowStatus: pick(['flowStatus', 'flowstatusShow', 'flowStatusShow']),
+        requestMark: pick(['requestMark', 'requestmark']),
+        amount: parseAmount(record.amount ?? record.money ?? record.totalAmount ?? record.totalamount ?? record.sum ?? record.fee),
+    };
+}
+export function assertKnownKeys(args) {
+    const known = [...ALLOWED_INPUT_KEYS, ...RESUME_INPUT_KEYS];
+    const unknown = Object.keys(args).filter((key) => !known.includes(key));
+    if (unknown.length > 0) {
+        throw workflowValidationError('input_unknown_key', `workflow.todoSmartConvert 不接受字段：${unknown.join(', ')}；可用字段：${ALLOWED_INPUT_KEYS.join(', ')}`, { retryAllowed: false, details: { unknown, allowed: ALLOWED_INPUT_KEYS } });
+    }
+}
+/** `items` 的公共校验 + 去重（`group` 与 `aggregate` 共用，保证两段口径一致）。 */
+export function readItems(rawItems) {
+    if (!Array.isArray(rawItems)) {
+        throw workflowValidationError('items_invalid', 'items 必须是数组（通常是 workflow.todoSmartConvert 取数阶段返回的 items，或用户直接给出的待办条目）');
+    }
+    if (rawItems.length === 0) {
+        throw workflowValidationError('items_empty', 'items 为空数组，没有可汇总的待办');
+    }
+    if (rawItems.length > 500) {
+        throw workflowValidationError('items_too_many', `单次最多 500 条，收到 ${rawItems.length} 条；请先分页缩减范围`);
+    }
+    const seen = new Set();
+    const rows = [];
+    let duplicateCount = 0;
+    let unreadableCount = 0;
+    for (const raw of rawItems) {
+        const row = rowFromAny(raw);
+        if (!row) {
+            unreadableCount += 1;
+            continue;
+        }
+        const key = rowKeyOf(row);
+        if (seen.has(key)) {
+            duplicateCount += 1;
+            continue;
+        }
+        seen.add(key);
+        rows.push(row);
+    }
+    if (rows.length === 0) {
+        throw workflowValidationError('items_unreadable', 'items 里没有可解析的条目（每项都必须是对象）', { details: { received: rawItems.length, unreadable: unreadableCount } });
+    }
+    return { rawCount: rawItems.length, rows, duplicateCount, unreadableCount };
+}
+/** 读取带上下限的整数选项。 */
+export function readBoundedInt(value, name, fallback, min, max) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        throw workflowValidationError(`${name}_invalid`, `${name} 必须是 ${min}~${max} 的整数，收到 ${String(value)}`, { retryAllowed: false });
+    }
+    return parsed;
+}