weaver-work-cli 0.1.26 → 0.1.29

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

@@ -0,0 +1,348 @@
+import { workflowValidationError } from '../../errors.js';
+import { asRecord, readBoundedInt } from './todoSmartConvert.core.js';
+import { detectBusinessKind, isDeterministicGroupKind, GROUP_SUMMARY_TAIL_TEXT, } from './businessRules.js';
+import { fetchDetailFacts, stampsOfRows } from './todoSmartConvert.detail.js';
+import { ctxEmptyOf, groupItemsOf, rowsOfGroup, totalTodoCount, } from './todoSmartConvert.smartGroup.js';
+import { readFinalGroups, readSmartSummaryTitle } from './todoSmartConvert.summary.js';
+const INTERNAL_MESSAGE_SUMMARY_HINT = '内部留言：只按原文直接概括「谁说了什么」，不要过度解读、不要推测动机或影响，严格按本批 suggestedMaxChars 控制字数';
+/**
+ * 组摘要的固定尾巴一律用 `businessRules.GROUP_SUMMARY_TAIL_TEXT`（CLI 固定文案与喂模型的
+ * `stats.tail` 必须同一份，否则改一处就会两处不一致）。
+ */
+const GROUP_SUMMARY_TAIL = GROUP_SUMMARY_TAIL_TEXT;
+/** 组级摘要建议长度上限。 */
+const DEFAULT_GROUP_SUMMARY_MAX = 100;
+/** `¥123` / `￥1,280.50` / `123元` 三种写法；每条只取第一个命中，避免把「14 小时」当金额。 */
+const GROUP_AMOUNT_PATTERNS = [
+    /[¥￥]\s*(\d[\d,]*(?:\.\d{1,2})?)/u,
+    /(\d[\d,]*(?:\.\d{1,2})?)\s*元/u,
+];
+export function firstAmountOf(text) {
+    for (const pattern of GROUP_AMOUNT_PATTERNS) {
+        const matched = text.match(pattern);
+        if (!matched)
+            continue;
+        const value = Number(matched[1].replace(/,/gu, ''));
+        if (Number.isFinite(value) && value > 0)
+            return value;
+    }
+    return null;
+}
+/** `由 A、B、C 等 5 人发起`：≥4 人时只列前 3 个再补「等 N 人」。 */
+export function createrPhraseOf(creators) {
+    if (creators.length === 0)
+        return '';
+    if (creators.length <= 3)
+        return `由${creators.join('、')} 发起`;
+    return `由${creators.slice(0, 3).join('、')} 等 ${creators.length} 人发起`;
+}
+/** 组摘要素材：只取普通组的**汇总项**（`type:"group"`），优先组与单独条目都跳过。
+ *
+ * `isCtxEmpty`：详情数据为空的条目不喂给 AI，从素材里剔除；
+ * 一个汇总项剔除后一条不剩 ⇒ 整个汇总项不产批次（该组不涉及 AI）。
+ *
+ * `smartGroup` 已为确定性路径的二次分组汇总项写入固定 `summary`；AI 路径和内部留言仍可进入
+ * `groupSummaryBatches`，由后续阶段补写组摘要。
+ */
+export function collectGroupSummaryBatches(groups, isCtxEmpty, maxChars = DEFAULT_GROUP_SUMMARY_MAX) {
+    const batches = [];
+    for (const group of groups) {
+        if (group.topPriority)
+            continue;
+        const kind = detectBusinessKind(group.title);
+        for (const sub of groupItemsOf(group)) {
+            // CLI 已经写好固定文案 ⇒ 不需要模型再写一遍
+            if (isDeterministicGroupKind(kind) && (sub.summary ?? '').trim() !== '')
+                continue;
+            const allRows = Array.isArray(sub.requestDatas) ? sub.requestDatas : [];
+            const rows = isCtxEmpty ? allRows.filter((row) => !isCtxEmpty(row.requestId)) : allRows;
+            const emptySkipped = allRows.length - rows.length;
+            if (rows.length === 0) {
+                // 整个汇总项没有可喂给模型的正文 ⇒ 不涉及 AI。
+                // 正常情况下这条走不到：单条摘要恒非空（详情为空时 CLI 用标题兜底），
+                // 而「有摘要」的条目在 `loadCtxEmptyPredicate` 里直接判为「有素材」。
+                continue;
+            }
+            const items = rows.map((row) => ({
+                requestId: row.requestId,
+                requestNameTitle: row.requestNameTitle,
+                createrName: (row.createrName ?? '').trim(),
+                summary: row.summary ?? '',
+            }));
+            const creators = [];
+            for (const item of items) {
+                if (item.createrName && !creators.includes(item.createrName))
+                    creators.push(item.createrName);
+            }
+            const amounts = [];
+            for (const item of items) {
+                const amount = firstAmountOf(`${item.summary} ${item.requestNameTitle}`);
+                if (amount !== null)
+                    amounts.push(amount);
+            }
+            const amountReliable = items.length >= 2 && amounts.length === items.length;
+            batches.push({
+                groupId: sub.id,
+                parentGroupId: group.id,
+                parentTitle: group.title,
+                title: sub.title,
+                count: items.length,
+                totalCount: allRows.length,
+                kind,
+                ...(kind === 'internal-message' ? { hint: INTERNAL_MESSAGE_SUMMARY_HINT } : {}),
+                suggestedMaxChars: maxChars,
+                ...(emptySkipped > 0 ? { emptySkipped } : {}),
+                items,
+                stats: {
+                    count: items.length,
+                    /** 卡片上要显示的条数（含被剔除的条目）——「共 N 条」必须用它 */
+                    totalCount: allRows.length,
+                    creatorCount: creators.length,
+                    creators,
+                    createrPhrase: createrPhraseOf(creators),
+                    amount: amountReliable
+                        ? {
+                            count: amounts.length,
+                            min: Math.min(...amounts),
+                            max: Math.max(...amounts),
+                            sum: Number(amounts.reduce((sum, value) => sum + value, 0).toFixed(2)),
+                        }
+                        : null,
+                    tail: GROUP_SUMMARY_TAIL,
+                },
+            });
+        }
+    }
+    return batches;
+}
+/**
+ * 「没有 AI 素材」的判断器（按 requestId 现拉详情后判定）。
+ *
+ * 没有素材只有一种情形：详情本身就是空表单（`contextAvailable=false`）。
+ * 内部留言正文只做清洗，不因长度单独丢弃。
+ *
+ * **已有单条摘要的条目直接判「有素材」**（2026-10-26 用户定稿）：摘要本身就是概括过的正文，
+ * 组摘要可以直接消费它，不需要再为它拉详情。这一条把 finish 链路里「每条都回查详情」的
+ * 请求量直接压到 0（77 条数据实测从 77 次降到 0 次）。
+ *
+ * 剩下的条目才有必要拉详情（`fetchDetailFacts`：缓存优先，键 `requestId__lastFeedBackDateTime`）。
+ * 只收集**非优先组**的条目：优先组不产组摘要（`collectGroupSummaryBatches` 直接跳过），
+ * 拉它的详情纯属浪费。
+ *
+ * 取数失败的条目（`fact === undefined`）当「有素材」：宁可把标题+空摘要喂进去，也不要因为
+ * 一次网络抖动就把整组素材剔空。
+ */
+export async function loadCtxEmptyPredicate(env, groups, args = {}) {
+    const rows = groups
+        .filter((group) => !group.topPriority)
+        .flatMap((group) => rowsOfGroup(group));
+    /** 已有摘要 ⇒ 有素材，不查缓存不拉网 */
+    const withSummary = new Set();
+    const pending = new Set();
+    for (const row of rows) {
+        const requestId = String(row.requestId ?? '').trim();
+        if (!requestId)
+            continue;
+        if ((row.summary ?? '').trim() !== '')
+            withSummary.add(requestId);
+        else
+            pending.add(requestId);
+    }
+    // 已经有摘要的条目不必再看详情：即便 pending 里也有它，也以「有摘要」为准。
+    for (const requestId of withSummary)
+        pending.delete(requestId);
+    if (pending.size === 0)
+        return { isCtxEmpty: () => false, warnings: [] };
+    const { facts, warnings } = await fetchDetailFacts(env, [...pending], args, stampsOfRows(rows));
+    const emptyOf = ctxEmptyOf(facts);
+    return {
+        isCtxEmpty: (requestId) => (withSummary.has(requestId) ? false : emptyOf(requestId)),
+        warnings,
+    };
+}
+/**
+ * `stage=groupSummaryContext`：把每个汇总项的素材打包（一组一包，不切批）。
+ *
+ * 为什么**不切批**：组摘要要概括**整组**，切开就只能概括一半，模型会写出与 `count` 不符的句子。
+ * 组太大时宁可给一条 warning 提示「该组 N 条，上下文偏长」，也不拆。
+ *
+ * **详情全空的组不产批次**，直接保留现有分组结构；
+ * 混合组里详情为空的条目也从素材里剔除。
+ */
+export async function runGroupSummaryContext(args, env) {
+    const groups = await readFinalGroups(args, env);
+    const { isCtxEmpty, warnings: emptyWarnings } = await loadCtxEmptyPredicate(env, groups, args);
+    // 组摘要目标字数：用户给了就用用户的，没给才用默认 100。
+    const groupSummaryMaxChars = readBoundedInt(args.groupSummaryMaxChars, 'groupSummaryMaxChars', DEFAULT_GROUP_SUMMARY_MAX, 20, 1000);
+    const batches = collectGroupSummaryBatches(groups, isCtxEmpty, groupSummaryMaxChars);
+    const totalCount = totalTodoCount(groups);
+    const warnings = [...emptyWarnings];
+    const skippedEmpty = batches.reduce((sum, batch) => sum + (batch.emptySkipped ?? 0), 0);
+    if (skippedEmpty > 0) {
+        warnings.push(`组摘要素材里剔除了 ${skippedEmpty} 条详情为空的条目（它们的 summary 已用标题填充，不喂给 AI）`);
+    }
+    const missingSummary = batches.reduce((sum, batch) => sum + batch.items.filter((item) => !item.summary).length, 0);
+    if (missingSummary > 0) {
+        warnings.push(`有 ${missingSummary} 条单条摘要为空（先跑 stage=summary 效果更好）；`
+            + '组摘要会缺少这部分依据，请只按有摘要的条目概括，不要补写');
+    }
+    if (batches.length === 0) {
+        warnings.push('本次没有需要 AI 写组摘要的汇总项：所有二次分组汇总项的组摘要均由 CLI 固定生成');
+    }
+    const deterministicGroups = groups
+        .filter((group) => !group.topPriority
+        && isDeterministicGroupKind(detectBusinessKind(group.title)))
+        .reduce((sum, group) => sum + groupItemsOf(group).length, 0);
+    return {
+        data: {
+            smartSummaryTitle: readSmartSummaryTitle(args, `您当前有 ${totalCount} 条待办，清单如下：`),
+            totalCount,
+            wfIdGroup: groups,
+            groupSummaryBatches: batches,
+            groupSummaryStats: {
+                groupCount: batches.length,
+                itemTotal: batches.reduce((sum, batch) => sum + batch.count, 0),
+                withAmount: batches.filter((batch) => batch.stats.amount !== null).length,
+                skippedEmpty,
+                /** CLI 固定文案的汇总项个数（不进批次，`smartGroup` 阶段已写好） */
+                deterministicGroups,
+                tail: GROUP_SUMMARY_TAIL,
+                suggestedMaxChars: groupSummaryMaxChars,
+            },
+        },
+        warnings,
+    };
+}
+/** 校验并索引 `aiGroupSummaries`（`[{ groupId, summary }]`，与 `aiSummaries` 同风格）。 */
+export function readAiGroupSummaries(value) {
+    if (!Array.isArray(value)) {
+        throw workflowValidationError('ai_group_summaries_invalid', 'aiGroupSummaries 必须是数组，每项形如 { groupId, summary }；groupId 取 groupSummaryBatches[].groupId', { retryAllowed: false });
+    }
+    const map = new Map();
+    value.forEach((raw, index) => {
+        const label = `aiGroupSummaries[${index}]`;
+        const record = asRecord(raw);
+        if (!record) {
+            throw workflowValidationError('ai_group_summaries_invalid', `${label} 必须是对象 { groupId, summary }`, { retryAllowed: false });
+        }
+        const unknownKeys = Object.keys(record).filter((key) => !['groupId', 'summary'].includes(key));
+        if (unknownKeys.length > 0) {
+            throw workflowValidationError('ai_group_summaries_invalid', `${label} 不接受字段：${unknownKeys.join(', ')}；只支持 groupId / summary`, { retryAllowed: false, details: { unknownKeys } });
+        }
+        const groupId = typeof record.groupId === 'string' ? record.groupId.trim() : '';
+        if (!groupId) {
+            throw workflowValidationError('ai_group_summaries_invalid', `${label}.groupId 必填且必须是字符串（形如 1003-1）`, { retryAllowed: false });
+        }
+        if (typeof record.summary !== 'string') {
+            throw workflowValidationError('ai_group_summaries_invalid', `${label}.summary 必须是字符串`, { retryAllowed: false });
+        }
+        if (map.has(groupId)) {
+            throw workflowValidationError('ai_group_summary_duplicate_group', `汇总项「${groupId}」出现了多次，一个汇总项只能有一个摘要`, { retryAllowed: true, details: { groupId } });
+        }
+        map.set(groupId, record.summary.trim());
+    });
+    return map;
+}
+/**
+ * `stage=groupSummary`：把模型写的组摘要填进 `displayItems[].summary`（只填 `type:"group"`）。
+ *
+ * 校验口径与单条摘要一致：未知 / 重复 `groupId` 硬失败（说明结果与本轮结构对不上），
+ * 漏写只给 warning 并留空串（模型漏一个组不该让 300 条重跑）。
+ *
+ * 额外做一条**软校验**：组里有发起人时，摘要必须包含由 CLI 算出的 `由 … 发起` 短语。
+ * 不满足只 warning 不失败——文案可以换个说法，但「漏掉发起人」通常是模型偷懒，
+ * 值得点名让它知道。
+ */
+export async function runGroupSummary(args, env) {
+    const groups = await readFinalGroups(args, env);
+    const summaries = readAiGroupSummaries(args.aiGroupSummaries);
+    const { isCtxEmpty, warnings: emptyWarnings } = await loadCtxEmptyPredicate(env, groups, args);
+    // 组摘要目标字数：与 `runGroupSummaryContext` 保持同一口径（用户给了就用用户的）。
+    const groupSummaryMaxChars = readBoundedInt(args.groupSummaryMaxChars, 'groupSummaryMaxChars', DEFAULT_GROUP_SUMMARY_MAX, 20, 1000);
+    const batches = collectGroupSummaryBatches(groups, isCtxEmpty, groupSummaryMaxChars);
+    const knownGroupIds = new Set(batches.map((batch) => batch.groupId));
+    for (const groupId of summaries.keys()) {
+        if (!knownGroupIds.has(groupId)) {
+            throw workflowValidationError('ai_group_summary_unknown_group', `aiGroupSummaries 里的 groupId「${groupId}」不在本次结构的汇总项里，不需要 AI 写摘要`
+                + '（请假/财务类固定文案，其他/内部留言汇总项交模型概括）；'
+                + `可回填的 groupId：${[...knownGroupIds].join(', ') || '（本次没有）'}`, { retryAllowed: true, details: { availableGroupIds: [...knownGroupIds] } });
+        }
+    }
+    const warnings = [...emptyWarnings];
+    let filled = 0;
+    let empty = 0;
+    let missingCreater = 0;
+    let tooLong = 0;
+    /** 沿用 CLI 固定文案（请假/财务）的汇总项个数 */
+    let deterministic = 0;
+    /** 最终结构里已经有组摘要的汇总项数量；摘要正文只保留在 displayItems[].summary。 */
+    let summarizedGroupCount = 0;
+    for (const group of groups) {
+        if (group.topPriority)
+            continue;
+        const kind = detectBusinessKind(group.title);
+        for (const sub of groupItemsOf(group)) {
+            if (isDeterministicGroupKind(kind)) {
+                // ★ 固定文案：`smartGroup` 阶段已写好，这里**不覆盖**。
+                if ((sub.summary ?? '').trim() === '') {
+                    const summary = summaries.get(sub.id) ?? '';
+                    sub.summary = summary;
+                    if (!summary) {
+                        empty += 1;
+                        continue;
+                    }
+                    filled += 1;
+                    summarizedGroupCount += 1;
+                    if (summary.length > groupSummaryMaxChars)
+                        tooLong += 1;
+                    const batch = batches.find((item) => item.groupId === sub.id);
+                    if (batch && batch.stats.createrPhrase && !summary.includes(batch.stats.createrPhrase)) {
+                        missingCreater += 1;
+                    }
+                    continue;
+                }
+                deterministic += 1;
+                summarizedGroupCount += 1;
+                continue;
+            }
+            const summary = summaries.get(sub.id) ?? '';
+            sub.summary = summary;
+            if (!summary) {
+                empty += 1;
+                continue;
+            }
+            filled += 1;
+            summarizedGroupCount += 1;
+            if (summary.length > groupSummaryMaxChars)
+                tooLong += 1;
+            const batch = batches.find((item) => item.groupId === sub.id);
+            if (batch && batch.stats.createrPhrase && !summary.includes(batch.stats.createrPhrase)) {
+                missingCreater += 1;
+            }
+        }
+    }
+    if (empty > 0)
+        warnings.push(`有 ${empty} 个汇总项没有拿到组摘要，summary 保持空串（未编造）`);
+    if (tooLong > 0) {
+        warnings.push(`有 ${tooLong} 个组摘要超过建议的 ${groupSummaryMaxChars} 字，已原样保留（CLI 不改写文案）`);
+    }
+    if (missingCreater > 0) {
+        warnings.push(`有 ${missingCreater} 个组摘要没有包含算好的「由 … 发起」短语（发起人由 CLI 统计，模型不该自己数），`
+            + '如需统一口径可重跑模型侧');
+    }
+    return {
+        data: {
+            smartSummaryTitle: readSmartSummaryTitle(args, `您当前有 ${totalTodoCount(groups)} 条待办，清单如下：`),
+            totalCount: totalTodoCount(groups),
+            wfIdGroup: groups,
+        },
+        meta: {
+            groupSummarized: filled,
+            groupEmpty: empty,
+            /** 沿用 CLI 固定文案的汇总项个数（请假/财务，不经过模型） */
+            groupDeterministic: deterministic,
+            groupSummaryCount: summarizedGroupCount,
+        },
+        warnings,
+    };
+}

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

@@ -0,0 +1,222 @@
+import { workflowValidationError } from '../../errors.js';
+import { planTodoOutput } from './todoOutputPlanner.js';
+import { assertKnownKeys, buildSkillTiming, CATEGORY_VALUES, DEFAULT_CATEGORY, DEFAULT_FETCH_LIMIT, DEFAULT_TOP_N, FETCH_PAGE_SIZE, GROUP_BY_VALUES, MAX_FETCH_LIMIT, MAX_FETCH_PAGES, STAGE_VALUES, workflowSuccess, } from './todoSmartConvert.core.js';
+import { collectRawTodos } from './todoSmartConvert.collect.js';
+import { runSmartConvert } from './todoSmartConvert.aggregate.js';
+import { runGroup } from './todoSmartConvert.group.js';
+import { inferStage, readStage } from './todoSmartConvert.pipeline.js';
+import { runSmartGroup } from './todoSmartConvert.smartGroup.js';
+import { runSummary, runSummaryContext } from './todoSmartConvert.summary.js';
+import { runGroupSummary, runGroupSummaryContext } from './todoSmartConvert.groupSummary.js';
+import { schemaOf, } from '../types.js';
+const inputSchema = schemaOf({
+    stage: {
+        type: 'string',
+        enum: [...STAGE_VALUES],
+        default: 'auto',
+        description: '阶段：auto、collect、group、smartGroup、summaryContext、summary、groupSummaryContext、groupSummary 或 aggregate。',
+    },
+    items: {
+        type: 'array',
+        minItems: 1,
+        maxItems: MAX_FETCH_LIMIT,
+        description: '待办条目。未传时 collect 出网取数；传入后只做本地归一、分组或摘要回填。',
+        items: { type: 'object' },
+    },
+    aiGroups: {
+        type: 'array',
+        description: 'smartGroup 的二次分组计划。每项必须提供 groupId、title，以及 requestIds 与 seq 二选一。',
+        items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                groupId: { type: 'string' },
+                title: { type: 'string' },
+                requestIds: { type: 'array', minItems: 1, items: { type: 'string' } },
+                seq: { type: 'array', minItems: 1, items: { type: 'integer', minimum: 1 } },
+            },
+            required: ['groupId', 'title'],
+            oneOf: [{ required: ['requestIds'] }, { required: ['seq'] }],
+        },
+    },
+    aiSummaries: {
+        type: 'array',
+        description: 'summary 阶段的单条摘要回填。',
+        items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { requestId: { type: 'string' }, summary: { type: 'string' } },
+            required: ['requestId', 'summary'],
+        },
+    },
+    aiGroupSummaries: {
+        type: 'array',
+        description: 'groupSummary 阶段的汇总项摘要回填。',
+        items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { groupId: { type: 'string' }, summary: { type: 'string' } },
+            required: ['groupId', 'summary'],
+        },
+    },
+    withDetailContext: { type: 'boolean', description: 'smartGroup 是否同进程生成单条摘要上下文。' },
+    withGroupSummaryContext: { type: 'boolean', description: 'summary 是否同进程生成组摘要上下文。' },
+    detailPrefetch: { type: 'boolean', description: '废弃兼容参数，已忽略；collect 只在给了 groupFocus 且意图适用于本组时按需预取分组字段（走详情缓存）。' },
+    groupBy: { type: 'string', enum: [...GROUP_BY_VALUES], default: 'workflow' },
+    groupOrder: { type: 'array', items: { type: 'string' } },
+    topN: { type: 'integer', minimum: 1, maximum: 50, default: DEFAULT_TOP_N },
+    limit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: MAX_FETCH_LIMIT,
+        default: DEFAULT_FETCH_LIMIT,
+        description: 'collect 目标条数；单页最多 ' + FETCH_PAGE_SIZE + ' 条，最多 ' + MAX_FETCH_PAGES + ' 页。',
+    },
+    pageSize: {
+        type: 'integer',
+        minimum: 1,
+        maximum: FETCH_PAGE_SIZE,
+        description: '废弃兼容参数；页大小由 limit 推导，传入值只产生 warning。',
+    },
+    category: { type: 'string', enum: [...CATEGORY_VALUES], default: DEFAULT_CATEGORY },
+    tabid: { type: 'string' },
+    tabName: { type: 'string' },
+    subCategory: { type: 'string' },
+    workflow: { type: 'array', items: { type: 'string' } },
+    creator: { type: 'string' },
+    requestName: { type: 'string' },
+    receiveTime: { type: 'string' },
+    requestLevel: { type: 'string' },
+    groupFocus: { type: 'string' },
+    maxCharsPerBatch: { type: 'integer', minimum: 500, maximum: 200000, default: 24000 },
+    maxItemsPerBatch: { type: 'integer', minimum: 1, maximum: 500, default: 100 },
+    summaryMaxChars: { type: 'integer', minimum: 10, maximum: 500, default: 50 },
+    groupSummaryMaxChars: { type: 'integer', minimum: 20, maximum: 1000, default: 100 },
+    detailConcurrency: { type: 'integer', minimum: 1, maximum: 32, default: 10 },
+    detailTimeoutMs: { type: 'integer', minimum: 1000, maximum: 60000, default: 10000 },
+    skillTiming: { type: 'object' },
+    query: { type: 'object' },
+    fetched: { type: 'integer' },
+    warnings: { type: 'array', items: { type: 'string' } },
+    markdown: { type: 'string' },
+    smartSummaryTitle: { type: 'string' },
+    smartSmmaryTitle: { type: 'string', description: '兼容旧回灌数据；请使用 smartSummaryTitle。' },
+    totalCount: { type: 'integer' },
+    wfIdGroup: { type: 'array', items: { type: 'object' } },
+    summaryBatches: { type: 'array', items: { type: 'object' } },
+    summaryStats: { type: 'object' },
+    groupSummaryBatches: { type: 'array', items: { type: 'object' } },
+    groupSummaryStats: { type: 'object' },
+    groupInfo: { type: 'object' },
+    groupingBrief: { type: 'array', items: { type: 'object' } },
+    detailStats: { type: 'object' },
+});
+function finish(env, args, startedAt, stage, data, meta, warnings) {
+    const timing = buildSkillTiming(stage, args.skillTiming, startedAt);
+    const planned = planTodoOutput({
+        ctx: env.ctx,
+        operation: 'workflow.todoSmartConvert',
+        data,
+        meta: { ...(meta ?? {}), timing },
+        warnings,
+    });
+    return workflowSuccess('workflow.todoSmartConvert', planned.data, planned.meta, warnings);
+}
+export const workflowTodoSmartConvertOperations = [{
+        name: 'workflow.todoSmartConvert',
+        resource: 'workflow',
+        method: 'todoSmartConvert',
+        action: 'workflow.todoSmartConvert',
+        summary: '待办智能汇总：collect 取数，group 分组，smartGroup 组装分组，summary 回填摘要，aggregate 保留旧汇总行为。',
+        capability: 'search',
+        risk: 'read',
+        inputSchema,
+        handler: async (args, env) => {
+            assertKnownKeys(args);
+            const startedAt = Date.now();
+            const stage = args.stage === undefined || args.stage === null || args.stage === ''
+                ? inferStage(args)
+                : readStage(args.stage);
+            const hasItems = Array.isArray(args.items);
+            const resumed = stage === 'collect' && hasItems;
+            if ((stage === 'group' || stage === 'smartGroup' || stage === 'aggregate') && !hasItems) {
+                throw workflowValidationError('items_required', 'stage=' + stage + ' 需要 items：先执行 stage=collect，再回灌 data.items', { retryAllowed: false });
+            }
+            if (stage === 'smartGroup') {
+                const result = await runSmartGroup(args, env);
+                if (args.withDetailContext === true) {
+                    const context = await runSummaryContext({
+                        ...args,
+                        wfIdGroup: result.data.wfIdGroup,
+                        smartSummaryTitle: result.data.smartSummaryTitle,
+                        totalCount: result.data.totalCount,
+                    }, env, result.facts);
+                    return finish(env, args, startedAt, stage, { ...result.data, summaryBatches: context.data.summaryBatches, summaryStats: context.data.summaryStats }, { branch: 'todo-smart-convert', stage, aiGrouped: Array.isArray(args.aiGroups), withDetailContext: true }, [...result.warnings, ...context.warnings]);
+                }
+                return finish(env, args, startedAt, stage, result.data, { branch: 'todo-smart-convert', stage, aiGrouped: Array.isArray(args.aiGroups) }, result.warnings);
+            }
+            if (stage === 'summaryContext') {
+                const result = await runSummaryContext(args, env);
+                return finish(env, args, startedAt, stage, result.data, {
+                    branch: 'todo-smart-convert', stage, detailSource: 'REQUEST_DETAIL',
+                }, result.warnings);
+            }
+            if (stage === 'summary') {
+                if (!Array.isArray(args.aiSummaries)) {
+                    throw workflowValidationError('ai_summaries_required', 'stage=summary 需要 aiSummaries：先执行 stage=summaryContext', { retryAllowed: false });
+                }
+                const result = await runSummary(args, env);
+                if (args.withGroupSummaryContext === true) {
+                    const context = await runGroupSummaryContext({
+                        wfIdGroup: result.data.wfIdGroup,
+                        smartSummaryTitle: result.data.smartSummaryTitle,
+                        totalCount: result.data.totalCount,
+                    }, env);
+                    if (Array.isArray(context.data.groupSummaryBatches) && context.data.groupSummaryBatches.length === 0) {
+                        return finish(env, args, startedAt, stage, result.data, {
+                            branch: 'todo-smart-convert', stage, aiSummarized: true, withGroupSummaryContext: true, ...result.meta,
+                        }, result.warnings);
+                    }
+                    return finish(env, args, startedAt, stage, {
+                        ...result.data,
+                        groupSummaryBatches: context.data.groupSummaryBatches,
+                        groupSummaryStats: context.data.groupSummaryStats,
+                    }, {
+                        branch: 'todo-smart-convert', stage, aiSummarized: true, withGroupSummaryContext: true, ...result.meta,
+                    }, [...result.warnings, ...context.warnings]);
+                }
+                return finish(env, args, startedAt, stage, result.data, {
+                    branch: 'todo-smart-convert', stage, aiSummarized: true, ...result.meta,
+                }, result.warnings);
+            }
+            if (stage === 'groupSummaryContext') {
+                const result = await runGroupSummaryContext(args, env);
+                return finish(env, args, startedAt, stage, result.data, {
+                    branch: 'todo-smart-convert', stage, deterministic: true,
+                }, result.warnings);
+            }
+            if (stage === 'groupSummary') {
+                if (!Array.isArray(args.aiGroupSummaries)) {
+                    throw workflowValidationError('ai_group_summaries_required', 'stage=groupSummary 需要 aiGroupSummaries：先执行 stage=groupSummaryContext', { retryAllowed: false });
+                }
+                const result = await runGroupSummary(args, env);
+                return finish(env, args, startedAt, stage, result.data, {
+                    branch: 'todo-smart-convert', stage, aiSummarized: true, ...result.meta,
+                }, result.warnings);
+            }
+            if (stage === 'group' || resumed) {
+                return finish(env, args, startedAt, 'group', runGroup(args), {
+                    branch: 'todo-smart-convert', stage: 'group', deterministic: true, ...(resumed ? { resumed: true } : {}),
+                });
+            }
+            if (stage === 'collect' || !hasItems) {
+                const result = await collectRawTodos(args, env);
+                return finish(env, args, startedAt, 'collect', result, {
+                    branch: 'todo-smart-convert', stage: 'collect',
+                }, result.warnings);
+            }
+            return finish(env, args, startedAt, 'aggregate', runSmartConvert(args), {
+                branch: 'todo-smart-convert', stage: 'aggregate', deterministic: true,
+            });
+        },
+    }];

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

@@ -0,0 +1,66 @@
+import { workflowValidationError } from '../../errors.js';
+import { STAGE_VALUES } from './todoSmartConvert.core.js';
+export function readStage(value) {
+    if (value === undefined || value === null || value === '')
+        return 'auto';
+    const text = String(value);
+    if (STAGE_VALUES.includes(text))
+        return text;
+    throw workflowValidationError('stage_invalid', `stage 只支持 ${STAGE_VALUES.join(' / ')}，收到 ${text}`, { retryAllowed: false, details: { allowed: STAGE_VALUES } });
+}
+/**
+ * 没显式给 `stage` 时，按**入参形态**推断下一步。
+ *
+ * 为什么必须推断：`--input-ref <refId>` 与 `--input-json` **不能同时传**（CLI 侧互斥），
+ * 而最终结构 `{ smartSummaryTitle, wfIdGroup }` 里**故意没有 `stage` 键**（多一个都破坏与
+ * demo 的同构）。若不推断，`--input-ref <smartGroup 的 ref>` 会被当成 `auto` + 无 items ⇒
+ * 又去取一次数，整条串接就断了。
+ *
+ * 规则（只认「带最终结构」这一种形态，其它一律回落到 `auto`，保持旧行为）：
+ *  - 有 `wfIdGroup` + 有 `aiGroupSummaries` ⇒ `groupSummary`（组摘要回填）；
+ *  - 有 `wfIdGroup` + 有 `aiSummaries` ⇒ `summary`（单条回填）；
+ *  - 有 `wfIdGroup`，且结构里**已经有非空单条摘要** ⇒ `groupSummaryContext`（下一步该写组摘要了）；
+ *  - 有 `wfIdGroup`，单条摘要还全空 ⇒ `summaryContext`（下一步该拉详情写单条摘要）。
+ *
+ * 最后两条靠「有没有填过单条摘要」区分：填过就说明已经走过 `summary`，不该再白拉一次详情。
+ * 想强制重跑某一步时显式传 `stage` 即可，显式永远优先。
+ */
+export function inferStage(args) {
+    if (!Array.isArray(args.wfIdGroup))
+        return 'auto';
+    if (Array.isArray(args.aiGroupSummaries))
+        return 'groupSummary';
+    if (Array.isArray(args.aiSummaries))
+        return 'summary';
+    return hasAnyRequestSummary(args.wfIdGroup) ? 'groupSummaryContext' : 'summaryContext';
+}
+/** 从**未经校验**的分组对象里摊平出条目（推断阶段用，同时兼容新旧两种结构）。 */
+export function rowsOfRawGroup(group) {
+    if (!group)
+        return [];
+    if (Array.isArray(group.displayItems)) {
+        return group.displayItems.flatMap((item) => {
+            if (item?.type === 'group')
+                return Array.isArray(item.requestDatas) ? item.requestDatas : [];
+            if (item?.type === 'request')
+                return item.requestData ? [item.requestData] : [];
+            return [];
+        });
+    }
+    if (group.topPriority)
+        return Array.isArray(group.requestDatas) ? group.requestDatas : [];
+    return Array.isArray(group.smartGroup)
+        ? group.smartGroup.flatMap((sub) => (Array.isArray(sub?.requestDatas) ? sub.requestDatas : []))
+        : [];
+}
+/** 结构里任意一条 `requestDatas[].summary` 非空 ⇒ 单条摘要阶段已经做过。 */
+export function hasAnyRequestSummary(groups) {
+    for (const raw of groups) {
+        const rows = rowsOfRawGroup(raw);
+        if (rows.some((row) => typeof row?.summary === 'string' && row.summary.trim() !== '')) {
+            return true;
+        }
+    }
+    return false;
+}
+/** 只用于「接收时间区间」的比较与展示；识别不了的时间不参与区间，不猜。 */