weaver-work-cli 0.1.28 → 0.1.31

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

@@ -0,0 +1,540 @@
+import { workflowValidationError } from '../../errors.js';
+import { asRecord, readBoundedInt } from './todoSmartConvert.core.js';
+import { orderGroupsByIntent, readGroupOrder } from './todoSmartConvert.group.js';
+import { detectBusinessKind, needsRequestSummary, usesTitleSummary } from './businessRules.js';
+import { openSummaryCache } from './summaryCache.js';
+import { loadDetailContextProvider, stampsOfRows } from './todoSmartConvert.detail.js';
+import { requestItemsOf, rowsOfGroup, runSmartGroup, totalTodoCount, } from './todoSmartConvert.smartGroup.js';
+const DEFAULT_MAX_CHARS_PER_BATCH = 24_000;
+const DEFAULT_MAX_ITEMS_PER_BATCH = 100;
+const DEFAULT_REQUEST_SUMMARY_MAX = 50;
+const INTERNAL_MESSAGE_SUMMARY_HINT = '内部留言：只按原文直接概括「谁说了什么」，不要过度解读、不要推测动机或影响，严格按本批 suggestedMaxChars 控制字数';
+/** 兼容两种拼写：新结构用 `smartSummaryTitle`，早前产物里是 `smartSmmaryTitle`（少一个 m）。 */
+export function readSmartSummaryTitle(args, fallback) {
+    const value = args.smartSummaryTitle ?? args.smartSmmaryTitle;
+    return typeof value === 'string' && value.trim() !== '' ? value : fallback;
+}
+/**
+ * 读 `displayItems`，同时兼容旧回灌结构。
+ *
+ * 新结构：`[{type:"request",requestData}|{type:"group",id,title,count,summary,defaultExpanded,requestDatas}]`
+ * 旧结构：优先组 `requestDatas[]`、普通组 `smartGroup[]`（无 `type`、无 `defaultExpanded`）。
+ *
+ * 旧结构只可能出现在回灌数据里。这里统一归一成新结构，
+ * 免得为了几个字段名把已有产物全部作废。`defaultExpanded` 一律**重算**、不信任输入值。
+ */
+export function readDisplayItems(record, index, title, topPriority) {
+    if (Array.isArray(record.displayItems)) {
+        return record.displayItems.map((rawItem, itemIndex) => {
+            const label = `wfIdGroup[${index}]「${title}」.displayItems[${itemIndex}]`;
+            const item = asRecord(rawItem);
+            if (!item) {
+                throw workflowValidationError('wfidgroup_invalid', `${label} 必须是对象`, { retryAllowed: false });
+            }
+            if (item.type === 'request') {
+                const requestData = asRecord(item.requestData);
+                if (!requestData) {
+                    throw workflowValidationError('wfidgroup_invalid', `${label} 是 type:"request"，必须带 requestData 对象（一条待办的完整字段）`, { retryAllowed: false });
+                }
+                return { type: 'request', requestData: requestData };
+            }
+            if (item.type === 'group') {
+                const requestDatas = Array.isArray(item.requestDatas) ? item.requestDatas : null;
+                if (!requestDatas) {
+                    throw workflowValidationError('wfidgroup_invalid', `${label} 是 type:"group"，必须带 requestDatas 数组（折叠的明细）`, { retryAllowed: false });
+                }
+                return {
+                    type: 'group',
+                    id: typeof item.id === 'string' ? item.id : '',
+                    title: typeof item.title === 'string' ? item.title : '',
+                    count: requestDatas.length,
+                    summary: typeof item.summary === 'string' ? item.summary : '',
+                    defaultExpanded: false,
+                    requestDatas,
+                };
+            }
+            throw workflowValidationError('wfidgroup_invalid', `${label}.type 只支持 "request"（单独一条）/ "group"（汇总项），收到 ${JSON.stringify(item.type)}`, { retryAllowed: false });
+        });
+    }
+    // —— 旧结构兜底 ——
+    if (topPriority) {
+        const requestDatas = Array.isArray(record.requestDatas) ? record.requestDatas : null;
+        if (!requestDatas) {
+            throw workflowValidationError('wfidgroup_invalid', `wfIdGroup[${index}]「${title}」是优先组，必须带 displayItems 或旧结构的 requestDatas 数组`, { retryAllowed: false });
+        }
+        return requestItemsOf(requestDatas);
+    }
+    const legacy = Array.isArray(record.smartGroup) ? record.smartGroup : null;
+    if (!legacy) {
+        throw workflowValidationError('wfidgroup_invalid', `wfIdGroup[${index}]「${title}」是普通组，必须带 displayItems 或旧结构的 smartGroup 数组（先跑 stage=smartGroup）`, { retryAllowed: false });
+    }
+    return legacy.map((rawSub, subIndex) => {
+        const requestDatas = Array.isArray(rawSub?.requestDatas) ? rawSub.requestDatas : [];
+        return {
+            type: 'group',
+            id: typeof rawSub?.id === 'string' ? rawSub.id : `${record.id}-${subIndex + 1}`,
+            title: typeof rawSub?.title === 'string' ? rawSub.title : '',
+            count: requestDatas.length,
+            summary: typeof rawSub?.summary === 'string' ? rawSub.summary : '',
+            defaultExpanded: false,
+            requestDatas,
+        };
+    });
+}
+/**
+ * 最终结构的轻量校验：只认上面那两种组形态（优先组 / 普通组），其它一律报错（不静默修正）。
+ * `count` 一律**重算**成 `displayItems` 摊平后的条数——这是唯一计数规则，不采信输入里的 count。
+ */
+export function validateFinalGroups(value) {
+    return value.map((raw, index) => {
+        const record = asRecord(raw);
+        if (!record) {
+            throw workflowValidationError('wfidgroup_invalid', `wfIdGroup[${index}] 必须是对象`, { retryAllowed: false });
+        }
+        const id = typeof record.id === 'string' ? record.id.trim() : '';
+        const title = typeof record.title === 'string' ? record.title : '';
+        if (!id) {
+            throw workflowValidationError('wfidgroup_invalid', `wfIdGroup[${index}].id 必填且必须是字符串（19 位 id 用数字会失真）`, { retryAllowed: false });
+        }
+        const topPriority = record.topPriority === true;
+        const displayItems = readDisplayItems(record, index, title, topPriority);
+        const count = displayItems.reduce((sum, item) => sum + (item.type === 'group' ? item.requestDatas.length : 1), 0);
+        return topPriority
+            ? { id, topPriority: true, title, count, defaultExpanded: true, displayItems }
+            : { id, topPriority: false, title, count, defaultExpanded: false, displayItems };
+    });
+}
+/**
+ * 取最终结构：优先用回灌进来的 `wfIdGroup`（`stage=smartGroup` / `stage=summaryContext` 的产出），
+ * 否则由 `items` 现场重建（有 `aiGroups` 走兼容模式，没有就走确定性模式）。两条路都落到同一种
+ * `FinalWfIdGroup[]`。
+ *
+ * 重建要从详情里读指标（请假天数/金额），所以这里是 `async`——指标由 `runSmartGroup` 内部
+ * 现拉详情得到（详情缓存已删除），本函数不再自己算一份。
+ */
+export async function readFinalGroups(args, env) {
+    if (Array.isArray(args.wfIdGroup)) {
+        // 回灌的结构通常已经是排好序的；这里再套一次 `groupOrder` 只是为了「顺序意图在后续阶段才给出」
+        // 也能生效（重排是幂等的，顺序一致时结果不变）。
+        return orderGroupsByIntent(validateFinalGroups(args.wfIdGroup), readGroupOrder(args)).groups;
+    }
+    if (Array.isArray(args.items)) {
+        const { data } = await runSmartGroup(args, env);
+        return data.wfIdGroup;
+    }
+    throw workflowValidationError('final_groups_required', '缺少最终结构：用 --input-ref 回灌上一步（stage=smartGroup 或 stage=summaryContext）的输出，'
+        + '或传 items 现场重建（传 aiGroups 走 AI 分组，不传按业务类型确定性分组）', { retryAllowed: false });
+}
+export function collectSummaryUnits(groups) {
+    const units = [];
+    for (const group of groups) {
+        if (group.topPriority) {
+            if (!needsRequestSummary(detectBusinessKind(group.title)))
+                continue;
+            units.push({
+                groupId: group.id,
+                groupTitle: group.title,
+                // 优先组没有汇总项，用组自身 id 当键——组摘要那一步同样按这个键取
+                subGroupId: group.id,
+                subGroupTitle: group.title,
+                kind: detectBusinessKind(group.title),
+                rows: rowsOfGroup(group),
+            });
+            continue;
+        }
+        const kind = detectBusinessKind(group.title);
+        if (!needsRequestSummary(kind))
+            continue;
+        for (const item of group.displayItems) {
+            if (item.type === 'group') {
+                units.push({
+                    groupId: group.id,
+                    groupTitle: group.title,
+                    subGroupId: item.id,
+                    subGroupTitle: item.title,
+                    kind,
+                    rows: item.requestDatas,
+                });
+                continue;
+            }
+            // 单独展示的一条：键用 `request-<requestId>`，只参与单条摘要批次，不出组摘要
+            units.push({
+                groupId: group.id,
+                groupTitle: group.title,
+                subGroupId: `request-${item.requestData.requestId}`,
+                subGroupTitle: item.requestData.requestNameTitle ?? '',
+                kind,
+                rows: [item.requestData],
+            });
+        }
+    }
+    return units;
+}
+/**
+ * `stage=summaryContext`：按最终分组打包摘要批次，并按需获取详情。
+ *
+ *  - **详情为空的条目不喂给 AI**：不进批次，CLI 直接把 `requestNameTitle` 复制到它的
+ *    `summary`（单条数据也需要摘要，但没有上下文可概括，标题即摘要）；
+ *  - 某个分组下**详情全空** ⇒ 整组不产生批次，结构上保留父组。
+ *
+ * 输出带着完整的最终结构，因为下一步 `stage=summary`
+ * 既要摘要也要结构，而 `--input-ref` 一次只能回灌一份 data —— 把两者放在同一份里，
+ * 回灌链才只需要一次引用。
+ */
+export async function runSummaryContext(args, env, prefetched) {
+    const groups = await readFinalGroups(args, env);
+    const units = collectSummaryUnits(groups);
+    const skippedSatisfaction = groups
+        .filter((group) => usesTitleSummary(detectBusinessKind(group.title)))
+        .reduce((sum, group) => sum + rowsOfGroup(group).length, 0);
+    // 优先组是叠加视图 ⇒ 同一条待办会在两个位置各出现一次，统计口径必须去重。
+    const requestIds = [...new Set(units.flatMap((unit) => unit.rows.map((row) => row.requestId)))].filter(Boolean);
+    // 单条摘要目标字数：用户给了口径（如「每条 30 字」）就用用户的，没给才用默认 50。
+    const summaryMaxChars = readBoundedInt(args.summaryMaxChars, 'summaryMaxChars', DEFAULT_REQUEST_SUMMARY_MAX, 10, 500);
+    // 摘要缓存命中时直接回填，未命中的条目才进入 AI 批次。
+    //   预填必须在「准备详情」之前做——已有摘要的条目根本不需要详情（详情只为写摘要服务）。
+    const summaryCache = await openSummaryCache(env.ctx);
+    /** 已有摘要（缓存命中 / collect 已回填）而跳过 AI 的条数 */
+    let prefilled = 0;
+    const prefilledIds = new Set();
+    const needsDetail = [];
+    for (const unit of units) {
+        for (const row of unit.rows) {
+            const cached = summaryCache.get(row.requestId, row.lastFeedBackDateTime, summaryMaxChars);
+            if (cached) {
+                row.summary = cached;
+                prefilled += 1;
+                prefilledIds.add(row.requestId);
+                continue;
+            }
+            needsDetail.push(row.requestId);
+        }
+    }
+    // 详情缓存键依赖 lastFeedBackDateTime：从本轮条目里建 stamps，否则缓存永远 miss。
+    const stamps = stampsOfRows(units.flatMap((unit) => unit.rows));
+    const provider = await loadDetailContextProvider(env, [...new Set(needsDetail)], args, prefetched, stamps);
+    const maxChars = readBoundedInt(args.maxCharsPerBatch, 'maxCharsPerBatch', DEFAULT_MAX_CHARS_PER_BATCH, 500, 200_000);
+    const maxItems = readBoundedInt(args.maxItemsPerBatch, 'maxItemsPerBatch', DEFAULT_MAX_ITEMS_PER_BATCH, 1, 500);
+    const batches = [];
+    let contextAvailable = 0;
+    let contextEmpty = 0;
+    let titleCopied = 0;
+    /**
+     * 已经进过 AI 批次的 requestId。
+     *
+     * 优先组是叠加视图 ⇒ 同一条待办会先在优先组出现、再在工作流组出现。同一条只喂一次模型，
+     * 另一份副本由 `stage=summary` 回填时按 requestId 一并写上（`runSummary` 就是按 id 遍历的），
+     * 所以这里跳过不会让任何一份摘要空缺，只是省掉一次重复的上下文。
+     */
+    const claimed = new Set();
+    for (const unit of units) {
+        let bucket = [];
+        let chars = 0;
+        let seq = 0;
+        const flush = () => {
+            if (bucket.length === 0)
+                return;
+            seq += 1;
+            batches.push({
+                batchId: `${unit.subGroupId}#${seq}`,
+                groupId: unit.groupId,
+                groupTitle: unit.groupTitle,
+                subGroupId: unit.subGroupId,
+                subGroupTitle: unit.subGroupTitle,
+                itemCount: bucket.length,
+                charCount: chars,
+                kind: unit.kind,
+                ...(unit.kind === 'internal-message' ? { hint: INTERNAL_MESSAGE_SUMMARY_HINT } : {}),
+                suggestedMaxChars: summaryMaxChars,
+                items: bucket,
+            });
+            bucket = [];
+            chars = 0;
+        };
+        for (const row of unit.rows) {
+            // 摘要缓存已命中（上一步预填）⇒ 不再喂 AI
+            if (prefilledIds.has(row.requestId))
+                continue;
+            const { context, contextAvailable: available } = provider.get(row.requestId);
+            if (!available) {
+                // ★ 详情为空 ⇒ 不喂 AI，summary 直接复制标题（确定性操作，不走模型）。
+                //   这里**不做** claimed 跳过：叠加视图下每个副本各自持有 summary 字段，都得填一次。
+                const firstSeen = !row.requestId || !claimed.has(row.requestId);
+                if (!(row.summary ?? '').trim()) {
+                    row.summary = row.requestNameTitle ?? '';
+                    if (firstSeen)
+                        titleCopied += 1;
+                }
+                // 统计按 requestId 去重，避免同一条在优先组和工作流组里被数两遍
+                if (firstSeen) {
+                    contextEmpty += 1;
+                    if (row.requestId)
+                        claimed.add(row.requestId);
+                }
+                continue;
+            }
+            // 叠加视图：这条已经在别处进过批次，跳过当前副本（摘要回填按 requestId 覆盖两份）
+            if (row.requestId && claimed.has(row.requestId))
+                continue;
+            if (row.requestId)
+                claimed.add(row.requestId);
+            contextAvailable += 1;
+            const item = {
+                requestId: row.requestId,
+                requestNameTitle: row.requestNameTitle,
+                context,
+                contextAvailable: true,
+            };
+            const itemChars = context.length + row.requestNameTitle.length + 40;
+            if (bucket.length > 0 && (bucket.length >= maxItems || chars + itemChars > maxChars))
+                flush();
+            bucket.push(item);
+            chars += itemChars;
+        }
+        flush();
+    }
+    const warnings = [...provider.warnings];
+    if (skippedSatisfaction > 0) {
+        warnings.push(`有 ${skippedSatisfaction} 条满意度类待办不走 AI，summary 将在回填阶段直接使用条目标题`);
+    }
+    if (titleCopied > 0) {
+        warnings.push(`有 ${titleCopied} 条详情数据为空，已不喂给 AI，summary 直接使用标题（requestNameTitle）填充`);
+    }
+    if (prefilled > 0) {
+        warnings.push(`有 ${prefilled} 条已有本地摘要（key=requestId__lastFeedBackDateTime），未再调用 AI；`
+            + `本次需要 AI 写摘要的只剩 ${requestIds.length - prefilled - titleCopied} 条`);
+    }
+    return {
+        data: {
+            smartSummaryTitle: readSmartSummaryTitle(args, `您当前有 ${totalTodoCount(groups)} 条待办，清单如下：`),
+            totalCount: totalTodoCount(groups),
+            wfIdGroup: groups,
+            summaryBatches: batches,
+            summaryStats: {
+                requestTotal: requestIds.length,
+                /** 本次真正发出去的详情请求条数（摘要缓存命中的不发） */
+                detailFetched: provider.stats.fetched + provider.reused,
+                /** 其中由上一阶段（smartGroup）facts 直接复用、未发请求的条数 */
+                detailReused: provider.reused,
+                /** 其中真正走了 HTTP 的条数 */
+                detailNetworkFetched: provider.stats.fetched,
+                contextAvailable,
+                contextEmpty,
+                failed: provider.stats.failed,
+                titleCopied,
+                /** 本地摘要命中、跳过 AI 的条数 */
+                prefilled,
+                /** 单条摘要的目标字数（默认 50，可由 summaryMaxChars 覆盖） */
+                suggestedMaxChars: summaryMaxChars,
+                /** 内部留言类批次：摘要要按「最低推理强度」写 */
+                internalMessageBatches: batches.filter((batch) => batch.kind === 'internal-message').length,
+                skippedSatisfaction,
+                summaryCacheFile: summaryCache.file,
+                batchCount: batches.length,
+                /** 本次详情取数的并发与耗时（现场拉，不再是占位值） */
+                concurrency: provider.stats.concurrency,
+                durationMs: provider.stats.durationMs,
+                maxCharsPerBatch: maxChars,
+                maxItemsPerBatch: maxItems,
+            },
+        },
+        warnings,
+    };
+}
+/** 校验并索引 `aiSummaries`：扁平 `[{ requestId, summary }]`（与 `aiGroups` 同风格）。 */
+export function readAiSummaries(value) {
+    if (!Array.isArray(value)) {
+        throw workflowValidationError('ai_summaries_invalid', 'aiSummaries 必须是数组，每项形如 { requestId, summary }', { retryAllowed: false });
+    }
+    const map = new Map();
+    value.forEach((raw, index) => {
+        const label = `aiSummaries[${index}]`;
+        const record = asRecord(raw);
+        if (!record) {
+            throw workflowValidationError('ai_summaries_invalid', `${label} 必须是对象 { requestId, summary }`, { retryAllowed: false });
+        }
+        const unknownKeys = Object.keys(record).filter((key) => !['requestId', 'summary'].includes(key));
+        if (unknownKeys.length > 0) {
+            throw workflowValidationError('ai_summaries_invalid', `${label} 不接受字段：${unknownKeys.join(', ')}；只支持 requestId / summary`, { retryAllowed: false, details: { unknownKeys } });
+        }
+        const requestId = typeof record.requestId === 'string' ? record.requestId.trim() : '';
+        if (!requestId) {
+            throw workflowValidationError('ai_summaries_invalid', `${label}.requestId 必填且必须是字符串（19 位 id 用数字会失真）`, { retryAllowed: false });
+        }
+        if (typeof record.summary !== 'string') {
+            throw workflowValidationError('ai_summaries_invalid', `${label}.summary 必须是字符串`, { retryAllowed: false });
+        }
+        if (map.has(requestId)) {
+            throw workflowValidationError('ai_summary_duplicate_request', `requestId「${requestId}」在 aiSummaries 里出现了多次，一条数据只能有一个摘要`, { retryAllowed: true, details: { requestId } });
+        }
+        map.set(requestId, record.summary.trim());
+    });
+    return map;
+}
+/**
+ * `stage=summary`：把模型写的摘要填进最终结构中对应待办的 `summary`。
+ *
+ * 输出沿用目标 demo 的唯一业务结构：`smartSummaryTitle + totalCount + wfIdGroup`。
+ * 摘要只写入对应条目的 `summary`；后续组摘要直接消费 `wfIdGroup`，不额外输出重复映射。
+ *
+ * 漏写不报错（记 warning、留空串）——模型漏几条不该让整批 300 条重跑；但 id 不存在、
+ * 重复出现属于「结果与源数据对不上」，硬失败。
+ */
+export async function runSummary(args, env) {
+    const groups = await readFinalGroups(args, env);
+    const summaries = readAiSummaries(args.aiSummaries);
+    // 单条摘要目标字数：与 `runSummaryContext` 保持同一口径（用户给了就用用户的）。
+    const summaryMaxChars = readBoundedInt(args.summaryMaxChars, 'summaryMaxChars', DEFAULT_REQUEST_SUMMARY_MAX, 10, 500);
+    // ★ 本次 AI 写出来的摘要顺手进缓存（key=requestId__lastFeedBackDateTime），
+    //   下次同一条流程的待办再来时可以复用摘要。
+    const summaryCache = await openSummaryCache(env.ctx);
+    let cacheWritten = 0;
+    // 缓存预填（与 `summaryContext` 同口径）：只跑 `summary` 阶段时也能拿到已写好的摘要，
+    // 否则重跑 finish（不带 aiSummaries）会把整份摘要清成空串。
+    // 满意度类不走 AI、也不读缓存：直接用标题当摘要，保证 `summary` 不为空。
+    let titleSummary = 0;
+    for (const group of groups) {
+        if (usesTitleSummary(detectBusinessKind(group.title))) {
+            for (const row of rowsOfGroup(group)) {
+                if ((row.summary ?? '').trim())
+                    continue;
+                row.summary = row.requestNameTitle ?? '';
+                if ((row.summary ?? '').trim())
+                    titleSummary += 1;
+            }
+            continue;
+        }
+        for (const row of rowsOfGroup(group)) {
+            if (!row?.requestId || (row.summary ?? '').trim())
+                continue;
+            const cached = summaryCache.get(row.requestId, row.lastFeedBackDateTime, summaryMaxChars);
+            if (cached) {
+                row.summary = cached;
+            }
+        }
+    }
+    const knownRequestIds = new Set();
+    for (const group of groups) {
+        for (const row of rowsOfGroup(group)) {
+            if (row?.requestId)
+                knownRequestIds.add(row.requestId);
+        }
+    }
+    for (const requestId of summaries.keys()) {
+        if (!knownRequestIds.has(requestId)) {
+            throw workflowValidationError('ai_summary_unknown_request', `aiSummaries 里的 requestId「${requestId}」不在本次最终结构里（可能 id 传错，或摘要是上一轮数据留下的）`, { retryAllowed: true, details: { requestId } });
+        }
+    }
+    const warnings = [];
+    let filled = 0;
+    let empty = 0;
+    let tooLong = 0;
+    /** 详情为空、CLI 已用标题填充并被本次保留的条数 */
+    let titleKept = 0;
+    /** 本地摘要缓存命中（不是标题兜底）并被本次保留下来的条数 */
+    let prefilledKept = 0;
+    /** 统计用：同一条待办在叠加视图里出现两次，计数只算一次 */
+    const countedIds = new Set();
+    const applyAll = (rows) => {
+        for (const row of rows) {
+            const summary = summaries.get(row.requestId) ?? '';
+            const firstTime = !row.requestId || !countedIds.has(row.requestId);
+            if (row.requestId)
+                countedIds.add(row.requestId);
+            if (!summary && (row.summary ?? '').trim() !== '') {
+                // 没有 AI 摘要，但结构里已经有摘要：
+                //  - 详情为空 ⇒ CLI 用标题填的（确定性操作、不覆盖、不计空）；
+                //  - 本地缓存命中 ⇒ 已经是写过的摘要，同样保留。
+                if (firstTime) {
+                    if ((row.summary ?? '').trim() === (row.requestNameTitle ?? '').trim())
+                        titleKept += 1;
+                    else
+                        prefilledKept += 1;
+                }
+                continue;
+            }
+            if (summary) {
+                if (firstTime) {
+                    filled += 1;
+                    if (summary.length > summaryMaxChars)
+                        tooLong += 1;
+                }
+                if (summaryCache.set(row.requestId, row.lastFeedBackDateTime, summary, summaryMaxChars))
+                    cacheWritten += 1;
+            }
+            else if (firstTime) {
+                empty += 1;
+            }
+            // 空串就是空串：不拿标题凑、不编造
+            row.summary = summary;
+        }
+    };
+    for (const group of groups) {
+        if (!needsRequestSummary(detectBusinessKind(group.title)))
+            continue;
+        if (group.topPriority) {
+            applyAll(rowsOfGroup(group));
+            continue;
+        }
+        for (const item of group.displayItems) {
+            if (item.type === 'group') {
+                applyAll(item.requestDatas);
+                continue;
+            }
+            // 单独展示的一条：只回填它自己
+            applyAll([item.requestData]);
+        }
+    }
+    if (empty > 0) {
+        warnings.push(`有 ${empty} 条没有拿到 AI 摘要，summary 保持空串（未用标题兜底、未编造）`);
+    }
+    if (titleKept > 0) {
+        warnings.push(`有 ${titleKept} 条详情为空的条目保留 CLI 填充的标题摘要（不参与 AI 回填）`);
+    }
+    if (tooLong > 0) {
+        warnings.push(`有 ${tooLong} 条摘要超过目标长度 ${summaryMaxChars} 字（可按用户口径调整），已原样保留；`
+            + '如需控制长度请重跑模型侧（CLI 不改写文案）');
+    }
+    if (prefilledKept > 0) {
+        warnings.push(`有 ${prefilledKept} 条沿用本地摘要缓存（未重新生成）`);
+    }
+    const titleSummaryCount = groups
+        .filter((group) => usesTitleSummary(detectBusinessKind(group.title)))
+        .reduce((sum, group) => sum + rowsOfGroup(group).length, 0);
+    if (titleSummaryCount > 0) {
+        warnings.push(`有 ${titleSummaryCount} 条满意度类待办不调用 AI，summary 直接使用条目标题（保证非空）`);
+    }
+    // 缓存写不进去不致命：只是下次还得重新问 AI，不能因此让本轮结果失败。
+    let summaryCacheFile = summaryCache.file;
+    if (cacheWritten > 0) {
+        const written = await summaryCache.save();
+        if (written)
+            summaryCacheFile = written;
+        else
+            warnings.push(`摘要缓存写入失败（${cacheWritten} 条），本次结果不受影响；下次仍会重新生成`);
+    }
+    return {
+        data: {
+            smartSummaryTitle: readSmartSummaryTitle(args, `您当前有 ${totalTodoCount(groups)} 条待办，清单如下：`),
+            totalCount: totalTodoCount(groups),
+            wfIdGroup: groups,
+        },
+        meta: {
+            summarized: filled,
+            empty,
+            /** 单条摘要的目标字数（默认 50，可由 summaryMaxChars 覆盖） */
+            suggestedMaxChars: summaryMaxChars,
+            titleCopied: titleKept,
+            /** 本地摘要缓存命中、未重新生成的条数 */
+            prefilled: prefilledKept,
+            skippedSatisfaction: titleSummaryCount,
+            /** 满意度类用条目标题当摘要、未调用 AI 的条数 */
+            titleSummary,
+            /** 本次新写入缓存的条数 */
+            summaryCacheWritten: cacheWritten,
+            summaryCacheFile,
+        },
+        warnings,
+    };
+}
+// ---------------------------------------------------------------------------

package/docs/_catalog.md

@@ -16,6 +16,7 @@
 | OKR 目标管理（目标查询/详情、关键成果、目标对齐、评论）、okr operation、标准版与 ebuilder 双链路、写操作 prepare/apply | `docs/okr.md` |
 | eBuilder 表单（菜单定位、List/NList、字段/浏览、OpenAPI 与自定义接口）、ebuilder-form operation、写操作 prepare/apply | `docs/ebuilder-form.md` |
 | E10 ESB 中心自定义触发动作流（入参模板查询 / prepare-apply 触发）、esb operation | `docs/esb.md` |
+| 待办智能汇总（workflow 内独立分支：跨条目取数/分组/摘要/金额合计，与列表查询解耦） | `docs/todo-smart-convert/README.md` |
 | 事井然项目管理（项目/任务/字典/字段解析）、project operation、写操作 prepare/apply | `docs/project.md` |
 | 快速安装 CLI，并使用 CLI/Skill Maker 生成、验证、打包和安装业务模块 Skill | `docs/operation-manual.md` |
 | 把随包 Agent Skill 安装/升级到本机 Agent（Codex/WorkBuddy 目录、从本地仓库发布最新版） | `docs/agent-skill-install.md` |

package/docs/contract.md

@@ -4,7 +4,7 @@
 
 源码位于 `src/shortcuts/contract`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/contract/operations` 中按 operation class 维护。
 
-面向 Agent 的说明位于 `skills/weaver-e10-jinchengda`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-work-cli-jinchengda/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
+面向 Agent 的说明位于 `skills/weaver-e10-jinchengda`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-e10-jinchengda/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
 
 ## 公共前置
 
@@ -49,24 +49,48 @@ weaver-work-cli --json contract run contract.workflow.query --input-json '{"work
 |---|---|
 | 合同类型与模板 | `contract.type.tree`、`contract.template.tree`、`contract.template.list`、`contract.template.detail` |
 | 条款查询 | `contract.clause.tree`、`contract.clause.list`、`contract.clause.group.list`、`contract.clause.search`、`contract.clause.tags` |
+| 条款库维护 | `contract.clause.permission`、`contract.clause.types`、`contract.clause.check`、`contract.clause.browser`、`contract.clause.subcompany`；`contract.clause.category.*` / `contract.clause.*` / `contract.clause.group.*` 的 `create|update|delete` + `.prepare/.apply` |
 | 条款引用 | `contract.clause.reference.get`、`contract.clause.reference.save.prepare/apply` |
 | 签约主体 | `contract.subject.app`、`contract.subject.form`、`contract.subject.fields`、`contract.subject.options`、`contract.subject.query`、`contract.subject.create.prepare/apply` |
 | 流程解析 | `contract.workflow.query`、`contract.workflow.list`、`contract.workflow.form.info`（三段式：loadBaseParam → loadFrameParam → getFormLayout）、`contract.workflow.field.options` |
 | 流程写操作 | `contract.request.create.prepare/apply`、`contract.request.save.prepare/apply`、`contract.request.submit.prepare/apply`、`contract.request.supervise.prepare/apply` |
 | 流程状态 | `contract.request.status`、`contract.request.log` |
+| 合同智能审查 | `contract.review.upload`（ebContract 两段式上传 + 审查页）、`contract.review.export`（`getAiReviewRecord`） |
+| 发起流程入口 | `contract.flow.page`、`contract.flow.launch`（workflow 模块上传 + `automaticFormFilling`） |
+| 模板推荐 | `contract.recommend.doc`（`recommendContractDoc`） |
+| 文档比对 | `contract.compare.upload`（docCompared）、`contract.compare.search`、`contract.compare.versions`、`contract.compare.page`、`contract.compare.diff` |
+| 企业资信 | `contract.credit.page`（仅页面入口） |
+| 业绩核算 | `contract.performance.link/fields/source.entry`（纯本地）+ `contract.performance.menu.search/list.init/list.filters/list.query/receipt.query`（只读查询） |
+| 报价单转合同 | `contract.quote.rmb/sheets/parse/fill`（本地 OOXML 读写，零依赖） |
+| 合同智能助手 | `contract.assistant.init`、`contract.assistant.meta`、`contract.assistant.list`、`contract.assistant.doc.query`、`contract.assistant.config.query`、`contract.assistant.tips.query`、`contract.assistant.doc.folder.search`、`contract.assistant.keygroup.search`；`contract.assistant.create/delete`、`contract.assistant.doc.save`、`contract.assistant.agent.update`、`contract.assistant.tips.create/delete`、`contract.assistant.rule.classification.*`、`contract.assistant.rule.*`、`contract.assistant.rule.group.*`、`contract.assistant.element.create/delete`、`contract.assistant.flow.*`（写操作均 prepare/apply） |
 
 完整字段与风险等级以 `weaver-work-cli contract schema` 为准。
 
+## 文件上传与页面地址
+
+- 上传统一走 `POST /api/file/preUploadCheck` → `POST /api/file/module/upload`；`module` 按场景固定：审查 `ebContract`、流程 `workflow`、比对 `docCompared`，不可混用。
+- 预检返回非空 `fileid` 即为秒传，跳过第二段；否则用 `preUploadId` + `uploadType` 带文件本体上传。
+- 成功判据是拿到非空 `fileId`，HTTP 200 不算成功；`uploadType=chunk` 时以 `upload_chunk_unsupported` 停止。
+- 只接受 `.doc` / `.docx`，单文件上限 200MB。
+- `sp/` 页面地址由字符串字面拼接生成，**不做整体编码**：`:`、`/`、`?`、`&`、`=`、`[`、`]` 与中文保持原样；仅资信页 `name[N]` 的值做一次 `encodeURIComponent`。
+
+## 条款库鉴权门
+
+条款库全部 operation（含查询类）在发请求前先调 `GET /api/ebd/contract/component/checkPermissionV2?moduleFlag=termComponent`（带业务头 `ebbusinessid: 10000000000000000`），只有 `data.checkPermission === true` 才放行；否则返回 `policy/clause_no_permission`（退出码 6）并中止。条款写操作要求 `clauseNum` / `clauseVersion` / `clauseGroup` 必传，`contractType` 与 `contractTypeName` 成对，条款组 `belongSub` 必传（不分部传空串）。
+
 ## 业务成功码适配
 
 源资料中各接口的成功码字段并不统一，适配层按路径分组判定，不凭 HTTP 200 判定业务成功：
 
 | 路径 | 成功判定 |
 |---|---|
-| `/api/ebd/**` | 顶层 `code = 0` |
+| `/api/ebd/**` | 顶层 `code = 0` 或 `200`，且 `status` 不为 false、`fail` 不为 true |
+| `/api/file/**`、`/api/doc/**` | 顶层 `code = 0`/`200` 且 `status`/`fail` 未置失败；无 code 时以 `data` 是否落地为准 |
 | `/api/ebuilder/form/obj/getObjsByTag`、`/api/bs/ebuilder/app/tags/getAppIds`、`/api/ebuilder/common/ds/fields`、`/api/ebuilder/common/ds/options` | 顶层 `code = 200` 且 `status` 不为 false |
+| `/api/ebuilder/form/list/**`（助手列表 getListDatas） | 顶层 `code = 0`/`200` 且 `status` 不为 false |
 | `/api/ebuilder/form/dataset/v2/**` | `message.code = "0"` |
 | `/api/workflow/**` | `message.errcode = "0"`（`getFieldOption` 上游示例为 `200`，同样视为成功） |
+| `/api/workflow/core/flowPage/**`、`/api/workflow/core/form/**`、`/api/ebuilder/flow/form/**` | 无 `message` 节点；只有非 0/200 的 `errcode` 或 `fail=true` / `status=false` 才算失败 |
 
 ## 环境与 ID 约束
 
@@ -82,10 +106,21 @@ weaver-work-cli --json contract run contract.workflow.query --input-json '{"work
 - 写请求超时或断线返回 `partial/write_uncertain`（退出码 11），禁止自动重放。
 - `submitRequest` 返回 `1200306` 时解析缺失字段补全后重试（最多 3 轮）；返回 `1200301` 时停止并诊断会话状态。
 
+## 合同智能助手要点
+
+- ID 链路：`init` -> `meta`（ebFormId/viewId）-> `list`（ai_id）-> `config.query`（Control=rule_config_id、Extract=config_id）。
+- 列表接口 `total` 恒为 0，以返回行数为准；助手列表 type 固定 `ai_background_config`。
+- 启用/停用智能体只改 `status_info`；`display` 是平台保留字段，输入含 `display` 直接拒绝（`policy/display_forbidden`）。
+- 删除类接口普遍假成功（删助手/提示语/关联流程），apply 强制回读复核；关联流程删除强制带 `type=contract_ai_workflow_data`。
+- 内控规则三步：分类 -> 规则 -> 规则组关联 Control，缺最后一步页面不可见；`default_type` 服务端互斥（后写覆盖先写）。
+- `pzxx` / `element_mxb` / `contract_rule_source` 必须是 JSON 字符串，对象入参由 CLI 自动转换；`element_content` 与 `element_mxb` 两份重复数据都要传（缺省 content 由 CLI 生成）。
+- 助手关联流程 `toolId=803297036482249914` 固定；一个流程全局只能绑定一次；`showPosition=3` 需 `fieldId`、`term_config` 需 `contractTypeField`、`key_config` 不能为空（NEED-CONFIRM 由 CLI 强制校验）。
+- 提示语无编辑接口（先删后增），`aizjid` 序号由 CLI 按最大序号 +1 自动补算；saveAiDoc 同表按 id 覆盖，传 id 前先经 `queryAiDoc` 校验记录类型。
+
 ## 暂未实现
 
-企业资信查询、企业变更、企业监控和撤回/退回流程在源资料中缺少接口路径、参数或确认契约，已列入 `withheldOperations`，详见 `skills/weaver-work-cli-jinchengda/references/contract-disabled-capabilities.md`。
+企业资信**数据**查询（诉讼、被执行、变更、监控）和撤回/退回流程在源资料中缺少接口路径、参数或确认契约，已列入 `withheldOperations`；资信只提供页面入口 `contract.credit.page`。详见 `skills/weaver-e10-jinchengda/references/contract-disabled-capabilities.md`。
 
 ## 源资料指纹
 
-`skills/weaver-work-cli-jinchengda/references/source-manifest.json` 记录了源资料的 `sha256` 与聚合指纹，用于后续检测源资料更新；更新检测确认前不要覆盖已生成的 CLI 与 Skill。
+`skills/weaver-e10-jinchengda/references/source-manifest.json` 记录了源资料的 `sha256` 与聚合指纹，用于后续检测源资料更新；更新检测确认前不要覆盖已生成的 CLI 与 Skill。