weaver-work-cli 0.1.26 → 0.1.29

package/docs/fna.md

@@ -1,16 +1,16 @@
 # 齐业成费控中心（FNA）CLI
 
-对应 `src/shortcuts/fna`，把泛微齐业成 FNA 费控中心 11 个源接口固化为 13 个 operation（预算 2 / 费用中心 3 / 借款管理 4 / 发票核销 4，其中提醒还款与催票为 prepare/apply 写链）。源资料：`/Users/zhufangyuan/Desktop/weaver-e10-qiyecheng`（指纹见 `skills/weaver-e10-qiyecheng/references/source-manifest.json`）。
+对应 `src/shortcuts/fna`，把泛微齐业成 FNA 费控中心 12 个源接口固化为 14 个 operation（预算 2 / 费用中心 3 + 报销报表 AI 问答 1 / 借款管理 4 / 发票核销 4，其中提醒还款与催票为 prepare/apply 写链）。源资料：`/Users/zhufangyuan/Desktop/weaver-e10-qiyecheng`（指纹见 `skills/weaver-e10-qiyecheng/references/source-manifest.json`）。
 
 ## 公共前置
 
-- 认证、profile、HTTP client 由 `src/internal/e10` 托管；业务 host 只适配 `/api/fna/` 与 `/api/app/fna/` 路径（`src/shortcuts/fna/host.ts` 的 `assertPath` 白名单）。
+- 认证、profile、HTTP client 由 `src/internal/e10` 托管；业务 host 只适配 `/api/fna/`、`/api/app/fna/` 与 `/api/secondev/fna/` 路径（`src/shortcuts/fna/host.ts` 的 `assertPath` 白名单）。
 - 成功判定统一走 WeaResult（`success` 或 `status` 布尔 / `code==200`）；费用中心 AI 查询用 `success`，预算/借款/核销用 `status`。
 - JSON 输出与错误 envelope、退出码遵循共享规则；写操作不满足确认条件返回 `confirmation.required`（exit 10），请求发出后结果不确定返回 `partial/write_uncertain`（exit 11）。
 
 ## Agent 入口
 
-面向 Agent 时先读 `skills/weaver-e10-qiyecheng/SKILL.md`，再按入口路由读取 `references/`（catalog/budget/expense-center/loan-management/invoice-writeoff）。
+面向 Agent 时先读 `skills/weaver-e10-qiyecheng/SKILL.md`，再按入口路由读取 `references/`（catalog/budget/expense-center/expense-chart/loan-management/invoice-writeoff）。
 
 ## Operation 目录
 
@@ -21,6 +21,7 @@
 | `fna.expense.reimbursed.sum` | read | POST `expense/center/getSumReimbursedAmountByAi`；body 可空 |
 | `fna.expense.loan.sum` | read | POST `expense/center/getSumLoanAmountByAi`；只认数字 ID；空 data 自动重试 2 次；已知仅统计首条记录缺陷 |
 | `fna.expense.prepay.writeoff.sum` | read | POST `expense/center/selectPrepayWriteOffAmountBySkill`；body 可空 |
+| `fna.expense.chart` | read | GET `getExpenseChart`（`/api/secondev/fna/`）；`userInput` 必填 ≤500 字；`maxRows` 本地截断 1-5000，默认 200；超时 180s；返回 `kind=rows/empty/clarify/blocked/unexpected` |
 | `fna.loan.main.page` | read | POST `loanManagementMenu/mainPage` |
 | `fna.loan.main.list` | read | POST `loanManagementMenu/mainPageList`；`current`/`pageSize`/`menuCode`/`permissionSetCode` 必填 |
 | `fna.loan.remind.repay.prepare` | write | 校验 displayData 行并预览，不发送 |
@@ -39,6 +40,7 @@ Windows PowerShell：
 ```powershell
 weaver-work-cli --json fna run fna.budget.application.detail --input-json '{"requestId":"1001"}'
 weaver-work-cli --json fna run fna.expense.reimbursed.sum --input-json '{"startDate":"2026-01-01","endDate":"2026-08-31"}'
+weaver-work-cli --json fna run fna.expense.chart --input-json '{"userInput":"2026-08 各部门报销金额排名前三"}'
 weaver-work-cli --json fna run fna.loan.main.list --input-json '{"current":1,"pageSize":20,"menuCode":"fesx_fna_borrowingManagement","permissionSetCode":"fesx_fna_borrowingManagement.default"}'
 weaver-work-cli --json fna run fna.invoice.writeoff.list --input-json '{"current":1,"pageSize":20,"invoiceStatus":"unarrivedTicket"}'
 ```
@@ -48,6 +50,7 @@ macOS/Linux（bash/zsh）：
 ```bash
 weaver-work-cli --json fna run fna.budget.application.detail --input-json '{"requestId":"1001"}'
 weaver-work-cli --json fna run fna.expense.reimbursed.sum --input-json '{"startDate":"2026-01-01","endDate":"2026-08-31"}'
+weaver-work-cli --json fna run fna.expense.chart --input-json '{"userInput":"2026-08 各部门报销金额排名前三"}'
 weaver-work-cli --json fna run fna.loan.main.list --input-json '{"current":1,"pageSize":20,"menuCode":"fesx_fna_borrowingManagement","permissionSetCode":"fesx_fna_borrowingManagement.default"}'
 weaver-work-cli --json fna run fna.invoice.writeoff.list --input-json '{"current":1,"pageSize":20,"invoiceStatus":"unarrivedTicket"}'
 ```
@@ -61,6 +64,7 @@ weaver-work-cli --json fna run fna.invoice.writeoff.list --input-json '{"current
 - 日期口径：报销按明细费用日期、借款按流程创建时间、预付核销按核销记录创建时间。
 - `menuCode`/`permissionSetCode` 环境相关，示例值需与环境核对。
 - 超 2^53 的 requestId 无法用 JS 数字精确表达，保留字符串并提示人工核验（真实环境 ID 一般在安全整数内，已按数字发送）。
+- `fna.expense.chart`：`code` 恒为 200，必须按 `data` 类型/`kind` 判成败；追问与安全拦截都是字符串 `data`，`meta.messageKindInferred=true` 表示归类为 CLI 推断。实测真实查询 3.3~66.6s，CLI 超时设 180s，禁止自动重试（每次都会消耗模型额度）。不做当前人强制过滤，结果可能是全租户范围；`userInput` 为商品化输入，个人口径必须改用 `fna.expense.reimbursed.sum`。二开包未安装时该 operation 会 404/500，需与其它 `fna.*` 正常但本 operation 失败区分。
 
 ## 验证
 

package/docs/invoice.md

@@ -77,7 +77,9 @@ weaver-work-cli --json invoice list --fields number,detailUrl
 | `invoice.reim.field.search` | 只读 | 搜索表单关联字段值，用于用户修正或出差客户确认 |
 | `invoice.reim.flow.create.prepare/apply` | 高风险写 | continuation 绑定已组装报销单 JSON；`work_flow_id/mainFormId/request_name/main_fields/detail_rows` 等字段在 schema 顶层逐项暴露，确认后调用 `createFlowNew` |
 | `invoice.reim.flow.update.prepare/apply` | 高风险写 | continuation 绑定更新报销单 JSON；确认后调用 `updateFlow` |
-| `invoice.issuing.make.prepare/apply` | 高风险写 | 固定销方信息，确认后调用 `makeInvoice` 开票或存台账 |
+| `invoice.issuing.qys.list` | 只读 | 获取待开票合同数据（含契约锁、泛微及其他合同），返回可开票行 `items` 与按「合同号 + 购方」汇总的 `groups`（开票金额合计按分累加、`blockedRows` 计不可开票行、`sellerNames` 为核算公司）；AI 开票据此调用 `weaver-e10-workflow` 发起开票流程草稿 |
+
+> 直接开票类 operation（`invoice.issuing.make.prepare/apply`、`invoice.issuing.qys.prepare`、`invoice.issuing.result`）已于 0.1.27 移除：开票按销售方选择流程草稿（销售方取台账「核算公司」，名称必须完全相同：「上海亘岩网络科技有限公司」走「契约锁合同收款发票开具及快递申请」；泛微网络、泛微软件、上海田亩、成都泛微、泛微国际、北京泛微、浙江泛微走「合同收款发票开具及快递申请」；为空或不在名单里时先问用户；退票、冲红、红冲走「合同开票冲红流程」），不再支持绕过流程直接调用 `makeInvoice`。
 
 共享、转让和标签仍暂不暴露给 Agent：新版源资料给出了提交接口，但还缺少稳定的接收人 `appid/cid/uid` 解析来源、标签关系查询和写后回查契约。
 
@@ -107,8 +109,6 @@ weaver-work-cli --json invoice import prepare --input-json '{"file":"./invoice.p
 weaver-work-cli --json invoice import apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
 
 weaver-work-cli --json invoice run invoice.reim.flow.create.prepare --input .\reim-create.json
-
-weaver-work-cli --json invoice run invoice.issuing.make.prepare --input .\issuing.json
 ```
 
 macOS/Linux（bash/zsh）：
@@ -121,13 +121,11 @@ weaver-work-cli --json invoice import prepare --input-json '{"file":"./invoice.p
 weaver-work-cli --json invoice import apply --input-json '{"file":"./invoice.pdf","continuation":"PREPARE_CONTINUATION","confirm":true}'
 
 weaver-work-cli --json invoice run invoice.reim.flow.create.prepare --input ./reim-create.json
-
-weaver-work-cli --json invoice run invoice.issuing.make.prepare --input ./issuing.json
 ```
 
 导入发票文件或远程 URL 时，面向 Agent 的正常链路是先 `invoice.ocr.preview`，再 `invoice.import.prepare` 使用 `validate=true`、`syncToOa=true`。只有用户明确要求跳过查验或离线导入时才传 `validate=false`；`validate=false` 表示跳过查验，不能描述为“查验通过”。`filedMap`、嵌套字段映射等 JSON 参数在 `--input-json` 中保持对象，CLI 只在 multipart 提交前序列化。
 
-报销单创建和开票/存台账只接受 Agent 已组装好的结构化 JSON。CLI 不负责猜测事前申请匹配、出差客户或税率；这些规则在 Skill reference 中指导 Agent 组装和展示预览。报销单创建的字段必须在 operation 顶层逐项传入，不再包一层通用 `payload`。当前修正资料包没有客户档案查询或红字发票红冲接口，`invoice.customer.*` 和 `invoice.red.*` 不暴露为 operation，Agent 不能绕过 CLI 调用原始接口。写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
+报销单创建只接受 Agent 已组装好的结构化 JSON；开票按销售方选择流程后，通过 `weaver-e10-workflow` 发起对应开票流程草稿（退票、冲红、红冲发起「合同开票冲红流程」），CLI 不再提供直接开票接口。CLI 不负责猜测事前申请匹配、出差客户或税率；这些规则在 Skill reference 中指导 Agent 组装和展示预览。报销单创建的字段必须在 operation 顶层逐项传入，不再包一层通用 `payload`。当前修正资料包没有客户档案查询或红字发票红冲接口，`invoice.customer.*` 和 `invoice.red.*` 不暴露为 operation，Agent 不能绕过 CLI 调用原始接口。写操作出现网络中断、部分成功、缺少回执 ID 或回查失败时，CLI 返回 `partial/write_uncertain`，Agent 禁止自动重复提交。
 
 ## 编辑白名单
 

package/docs/todo-smart-convert/README.md

@@ -0,0 +1,171 @@
+# todoSmartConvert
+
+`workflow.todoSmartConvert` 是 workflow 模块中的只读待办汇总 operation。它负责取数、归一化、首次分组、按需获取详情、单条摘要回填和兼容 `aggregate` 阶段的本地汇总；需要语义侧重点时校验调用方提供的 AI 分组计划，否则由 CLI 按业务规则确定性分组。
+
+## 1. 文档和代码边界
+
+本文件面向 CLI 维护者，记录当前行为、不变量和阶段边界。三份文档各自只承担一类职责：
+
+- Agent 如何判断意图、组织多轮回灌：[`skills/weaver-e10-workflow/references/todo-smart-convert.md`](../../skills/weaver-e10-workflow/references/todo-smart-convert.md)。
+- 各源码文件的详细职责：[`src/shortcuts/workflow/operations/todoSmartConvert/README.md`](../../src/shortcuts/workflow/operations/todoSmartConvert/README.md)。
+- 本文只保留实现约束，避免把调用指令和源码文件清单重复维护两遍。
+
+主入口只保留输入 schema、阶段路由、统一信封和耗时输出；实现按四层组织：
+
+| 层 | 负责内容 |
+| --- | --- |
+| 入口层 | operation 注册、schema、stage 路由、统一输出 |
+| 阶段层 | collect、group、smartGroup、summary、groupSummary、aggregate |
+| 领域层 | 首次/二次分组、业务类型识别、详情字段清洗、摘要素材 |
+| 基础设施层 | HTTP 详情抓取、摘要缓存、输入归一化、输出告警 |
+
+详情抓取和两个缓存是独立边界：列表阶段只按需要预取详情（有适用意图的组）；详情与摘要都以 `requestId__lastFeedBackDateTime` 为 key 落盘（7 天）；摘要缓存只省 AI，不省详情。
+
+## 2. 阶段
+
+| 阶段 | 作用 | 主要结果 |
+| --- | --- | --- |
+| `collect` | 调列表接口取数并完成首次分组 | `items`、`wfIdGroup`、`groupingBrief` |
+| `group` | 对已传入的 `items` 重新做首次分组 | 中间分组结构、统计和 Markdown |
+| `smartGroup` | 校验 AI 分组计划并组装最终结构 | `smartSummaryTitle`、`totalCount`、`wfIdGroup` |
+| `summaryContext` | 现场获取详情并按展示项生成摘要素材 | `summaryBatches`、`summaryStats` |
+| `summary` | 回填 `aiSummaries` | 最终结构，必要时附组摘要素材 |
+| `groupSummaryContext` | 生成汇总项摘要素材 | `groupSummaryBatches`、`groupSummaryStats` |
+| `groupSummary` | 回填 `aiGroupSummaries` | 最终结构 |
+| `aggregate` | 兼容本地汇总输入 | 分组、金额和 Markdown |
+
+常规调用链是：
+
+```text
+collect
+  -> smartGroup (可合并 withDetailContext)
+  -> summary (可合并 withGroupSummaryContext)
+  -> groupSummary（仅存在待回填批次时）
+```
+
+未传 `stage` 时：没有 `items` 走 `collect`；有 `items` 走兼容的本地汇总；回灌最终结构时按结构推断阶段。显式 `stage` 优先。
+
+## 3. 取数规则
+
+- 只调用对应分类的列表接口，默认待办使用 `getTodoListData`；collect 不调用总数、分组统计接口。
+- 时间条件一次传入，通过 `current` 递增翻页。默认 `limit=200`，最大 `limit=500`，单页最多 100 条，最多 5 页；`pageSize` 仅为兼容参数，实际由 `limit` 推导。
+- 页数不足、达到 limit 或页内无新增数据时停止；跨页按 `requestId` 去重。
+- 只读取响应中的 `displayData`。技术行不作为 `displayData` 缺失时的回退来源。
+- 长 ID 全程按字符串处理。`requestData` 只包含稳定业务字段，`workflowName`、接收时间和金额等辅助字段只留在内部行中。
+- **collect 只在有必要时预取详情**：用户给了 `groupFocus` 且意图适用于 `detectBusinessKind(组名)` 的组，才把该组条目的详情字段放进 `groupingBrief[].items[].fields`（≤8 字段、每值 ≤80 字）。预取走详情缓存，命中则零请求；`detailStats.groupingMaterial` 记录 `requested/cacheHit/fetched/failed/withFields`。
+- collect 会刷新本地查询快照，供后续批量操作的门禁使用；本 operation 本身不执行写操作。
+
+collect 输出的 `groupingBrief` 使用组内 1-based `idx`。模型生成 `aiGroups` 时优先使用 `seq`，避免手抄长 ID。
+
+## 4. 首次分组和二次分组
+
+### 首次分组
+
+- 默认按 `workflowName` 分组；也支持 `urgency`、`date`、`none`。
+- 优先组固定为 `id=priority`、标题“建议优先处理的流程”，排在第一位。超时条目必入；没有紧急级别 2 时才退到级别 1，级别 0 不因等级入选。
+- 优先组是**叠加视图**，不是筛选。入选条目仍保留在各自的工作流分组里（优先组只是置顶入口），因此各大组 `count` 之和会大于 `totalCount`；`totalCount` 按去重条数计，等于 collect 取到的全部条数。
+- 普通组默认保持接口首次出现顺序；`groupOrder` 只有在调用方明确提供顺序意图时才使用。
+
+### `aiGroups`
+
+`aiGroups` 是扁平数组，每项只能有 `groupId`、`title` 和 `requestIds` 或 `seq`：
+
+```json
+[
+  { "groupId": "workflow-id", "title": "安全通知", "seq": [1, 3] },
+  { "groupId": "workflow-id", "title": "制度通知", "seq": [2, 4] }
+]
+```
+
+- 优先组不接受二次分组。
+- 组内少于 3 条时全部单条展示，**即使给了 `aiGroups` 也忽略**（硬门槛优先，写 warning）。
+- 组内至少 3 条时：`aiGroups` 里属于本组的计划**只有在「意图适用本组」或「本组是内部留言」时才会被采纳**；其余情况等同于没传（写 warning，走确定性分组）。采纳时才校验未知组、未知条目、重复分配和越界序号。
+- 无侧重点时，普通子组按条数降序；有 `groupFocus` 时，子组顺序沿用 AI 数组顺序。
+- `aiGroups` 省略或传 `[]` 一律走确定性分组：只有请假（≤1 天）、财务（≤100 元）和客户问题支持类（已过期/今日到期）会产汇总项，其他类**全部平铺单条**（不再造同名汇总项）；满意度类全部单条，`summary` 用条目标题兜底。无法识别请假天数或金额的条目按单条展示并告警。
+  **内部留言是例外**：≥3 条时必须有 `aiGroups`（无侧重点 / 侧重点不适用 ⇒ 按**流程标题**分组；侧重点适用 ⇒ 按侧重点+详情），缺计划报 `ai_groups_required`，没有「平铺」这个第三态。
+- **意图按表判定**（`INTENT_RULES`）：专属意图（请假/财务/问题支持维度）只作用于对应类型，通用意图（客户/发起人/时间/紧急/标题主题…）只作用于内部留言与其他类；都不命中 = 没有意图，退回确定性规则，**不硬失败**。
+- AI 漏分、子组只剩 1 条、保留标题里超阈值的条目，**一律落成单条**，不造 `other`，并通过 warnings 说明条数。
+
+最终结构固定为：
+
+```json
+{
+  "smartSummaryTitle": "您当前有 N 条待办，清单如下：",
+  "totalCount": 0,
+  "wfIdGroup": [
+    {
+      "id": "workflow-id",
+      "topPriority": false,
+      "title": "工作流名称",
+      "count": 0,
+      "defaultExpanded": false,
+      "displayItems": [
+        { "type": "request", "requestData": {} },
+        {
+          "type": "group",
+          "id": "workflow-id-1",
+          "title": "子组名称",
+          "count": 0,
+          "summary": "",
+          "defaultExpanded": false,
+          "requestDatas": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+`totalCount` = **按 `requestId` 去重后的条数**（= collect 取到的全部条数），**不是** `wfIdGroup[].count` 之和（优先组是叠加视图）。只有优先组 `defaultExpanded=true`；普通组先放汇总项，再放单条。
+
+## 5. 详情、单条摘要和组摘要
+
+- 详情接口固定使用 `isReadRequest:false`，默认并发 10、单条超时 10 秒；单条失败不拖垮整批。
+- 详情字段先清洗 HTML/CSS，再按业务规则筛选；正文不做固定长度截断，也不因为长度被丢弃。
+- **两个持久化缓存**，key 都是 `requestId__lastFeedBackDateTime`，有效期 7 天、清理间隔 3 天、无版本号：
+  - `todo-detail-cache.json`：`context` / `contextAvailable` / `metrics` / `fields`，**详情为空也写**（否则每次都要重拉）；
+  - `todo-summary-cache.json`：单条摘要文本（`SUMMARY_CACHE_VERSION = 2`）。
+  位置优先级：`WEAVER_WORK_CLI_CACHE_DIR` → `WEAVER_WORK_CLI_SKILL_DIR` → 已知 Agent skill 目录 → CLI 状态目录兜底。
+- **摘要缓存只省 AI，不省详情**：阈值指标（请假天数/报销金额）只认流程详情数据，所以 `smartGroup` 对全部条目走一次「缓存优先」的详情取数（命中即零请求）。详情为空的条目不进入 `summaryBatches`，CLI 用标题兜底。
+- 详情请求**发生在 `smartGroup`**（`summary` 阶段复用同一份缓存，实测暖缓存 0 请求），因此看耗时与请求数要看 `smartGroup` 的 `summaryStats` / `detailStats`，不要再看 `summary` 阶段。
+- 单条摘要默认建议 50 字，组摘要默认建议 100 字；调用方可通过 `summaryMaxChars`、`groupSummaryMaxChars` 覆盖。CLI 只校验、告警和回填，不截断模型文案。
+- 摘要批次默认按 `maxCharsPerBatch=24000` 或 `maxItemsPerBatch=100` 切分；这两个参数只影响模型批次，不改变最终业务数据。
+- 确定性路径下请假、财务、客户问题支持的固定组摘要由 CLI 生成，其余类型无汇总项；显式 AI 分组路径的组摘要先留空，再由 `groupSummary` 回填。
+
+## 6. 输出和兼容边界
+
+- 最终业务数据完整返回，不因输出大小裁剪或改写；warnings 可在 operation 信封和 `meta.warnings` 中出现，其他诊断字段只放在 `meta`，不混入业务对象。
+- `detailPrefetch`、`pageSize` 和旧拼写 `smartSmmaryTitle` 仅为兼容入口，新调用使用当前字段。
+- `workflow.todoSmartConvert` 只读。提交、置已读、催办、共享、转发、退回等操作继续使用 `workflow.batch*`。
+
+## 7. 验证
+
+macOS/Linux：
+
+```bash
+npm run build
+npx tsc --noEmit --pretty false
+git diff --check
+```
+
+Windows PowerShell：
+
+```powershell
+npm run build
+npx tsc --noEmit --pretty false
+git diff --check
+```
+
+专项测试：
+
+macOS/Linux：
+
+```bash
+node --import tsx --test test/business/todoSmartConvert/todoSmartConvert.test.ts
+```
+
+Windows PowerShell：
+
+```powershell
+node --import tsx --test test/business/todoSmartConvert/todoSmartConvert.test.ts
+```

package/docs/todo-smart-convert/data-contract.md

@@ -0,0 +1,236 @@
+# todoSmartConvert 返回数据结构契约
+
+> 核对来源：`src/shortcuts/workflow/operations/todoSmartConvert/*`、`src/shortcuts/workflow/index.ts`、`src/shortcuts/workflow/operations.ts`
+> 核对日期：2026-10-27（ai二次分组改造收口）｜已用本地 `stage=smartGroup` 实跑验证（不走 OA 接口）
+
+## 0. 三层结构，别混着看
+
+```
+CLI 输出信封         { schemaVersion, ok, operation, data, meta, warnings }
+  └─ data（业务对象）  { smartSummaryTitle, totalCount, wfIdGroup }   ← 只有这三个键
+       └─ wfIdGroup[]  { id, topPriority, title, count, defaultExpanded, displayItems }
+            └─ displayItems[]  { type:"request", requestData } | { type:"group", …, requestDatas }
+                 └─ requestData  14 个固定字段
+```
+
+**诊断信息（warnings / timing / 各类 stats）一律在信封与 `meta` 里，不进 `data`。**
+
+## 1. 输出信封
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `schemaVersion` | number | 固定 `1` |
+| `ok` | boolean | 成功恒 `true`；失败时进程退出码非 0，**错误 JSON 只写 stderr** |
+| `operation` | string | 固定 `workflow.todoSmartConvert` |
+| `data` | object | 业务对象，见 §2 |
+| `meta` | object | `branch` / `stage` / 阶段标记（`aiGrouped`、`aiSummarized`、`deterministic`、`withDetailContext`、`resumed`）/ `timing` / **`warnings`** |
+| `warnings` | array | ⚠️ 实测**恒为空数组**，真实告警在 `meta.warnings`（见 §12-1） |
+
+`meta.timing` 形态：
+
+```json
+{ "startedAt": "…", "finishedAt": "…", "stage": "smartGroup",
+  "steps": [{ "name": "smartGroup", "kind": "cli|ai|stage", "durationMs": 4 }],
+  "durationMs": 4 }
+```
+
+- `kind:"ai"` 的步骤只有在调用方传了 `skillTiming.aiDurationMs > 0` 时才出现。
+- `durationMs` = `max(各步之和, 传入 startedAt 到现在的墙钟时间)`。
+
+该 operation 在输出层显式 `persist:false`：**不会产生 `refId` / `resultFile`，也不做 24 KB 折叠**。
+
+## 2. 业务对象（唯一合法形态）
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `smartSummaryTitle` | string | 默认 `您当前有 N 条待办，清单如下：`；上游传了 `smartSummaryTitle`（或旧拼写 `smartSmmaryTitle`）则沿用 |
+| `totalCount` | number | **按 `requestId` 去重后的条数**（= collect 取到的全部条数）。**不是** Σ `count`：优先组是叠加视图，同一条会同时出现在优先组和工作流组 |
+| `wfIdGroup` | array | 大分组数组，顺序 = 首次出现顺序（优先组恒第一） |
+
+键顺序固定为 `smartSummaryTitle → totalCount → wfIdGroup`，**不接受第四个键**。
+
+## 3. 组对象 `wfIdGroup[i]`
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `id` | string | 优先组恒 `"priority"`；普通组取 `workflowId`（同名多版本取第一个）；非 workflow 维度取分组键；未分类组可能回落成某条真实 `workflowId`（见 §12-3） |
+| `topPriority` | boolean | 只有「建议优先处理的流程」为 `true` |
+| `title` | string | 优先组固定文案；普通组 = `workflowName` |
+| `count` | number | **= 该组 `displayItems` 摊平后的条数**（回灌时会重算，不采信输入里的值） |
+| `defaultExpanded` | boolean | 只有优先组 `true`；普通组与汇总项恒 `false` |
+| `displayItems` | array | 混合数组：汇总项（`type:"group"`）在前，单条（`type:"request"`）在后 |
+
+优先组是**叠加视图**：入选优先组的条目**仍保留在各自工作流组里**（优先组只是置顶入口）。因此 Σ`count` > `totalCount` 是正常现象，差值 = 优先组条数。
+
+## 4. `displayItems[i]` 两种元素
+
+**单独一条：**
+
+```json
+{ "type": "request", "requestData": { … §5 } }
+```
+
+**汇总项（折叠）：**
+
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `type` | `"group"` | 固定 |
+| `id` | string | `父组id-序号`，如 `1003-1`，序号从 1 起（同组内重排后会变） |
+| `title` | string | 子组名：AI 给的名字 / CLI 三类固定标题（`1天以内` / `100元以内` / `已过期及今天即将过期的流程`）。**不存在** `other`、也**不存在**「与父组同名」的兜底标题 |
+| `count` | number | = `requestDatas.length` |
+| `summary` | string | 组摘要；确定性路径可能有固定文案，AI 路径未回填时为空串 |
+| `defaultExpanded` | boolean | 恒 `false`（汇总项一律收缩） |
+| `requestDatas` | array | 明细，元素同 §5 |
+
+## 5. `requestData` 14 个字段（全部必出）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `requestId` | string | 19 位，**禁止转数字** |
+| `workflowId` | string | 同上 |
+| `userMasterId` | string | 当前处理人 |
+| `isremark` | number | 0/1，是否已读语义位 |
+| `nodeId` | string | 当前节点 |
+| `overTime` | boolean | 是否超时（原始布尔位） |
+| `userOverTime` | string | 超时显示文案（`昨天到期` / `11-01到期`），**不一定代表已超时** |
+| `requestLevel` | number | 0 正常 / 1 重要 / 2 紧急 |
+| `requestLevelShow` | string | 已去掉 HTML 的等级文案 |
+| `requestNameTitle` | string | 标题（纯文本） |
+| `creater` | string | 发起人 ID |
+| `createrName` | string | 发起人姓名 |
+| `lastFeedBackDateTime` | string | 最后反馈时间，空串 = 无反馈；**摘要缓存与详情缓存 key 的一半**（`requestId__lastFeedBackDateTime`，流程有新反馈 ⇒ key 变 ⇒ 缓存自然失效） |
+| `summary` | string | 单条摘要，**恒为 string**，未写时 `""` |
+
+**不出现**在 `requestData` 里的字段（只在中间态 `items` 上）：`workflowName`、`receivedTime`、`flowStatus`、`requestMark`、`amount`、`stats`。
+
+## 6. 八条不变式（review 重点）
+
+| # | 不变式 | 校验位置 |
+|---|---|---|
+| 1 | `totalCount` = 按 `requestId` 去重后的条数（**不是** Σ `count`） | `totalTodoCount()` |
+| 2 | 每个 `count` = 该组 `displayItems` 摊平条数，**不采信输入** | `validateFinalGroups()` |
+| 3 | 每条待办在**一个组内**只出现一次；优先组的条目会同时出现在其工作流组（叠加视图） | `used` 集合 / `selectPriorityRows()` |
+| 4 | 组内 <3 条一律平铺单条，**不产生任何汇总项**（给了 `aiGroups` 也忽略） | `GROUP_MIN_ITEMS_FOR_SUBGROUP = 3` |
+| 5 | 汇总项 `id` = `父组id-序号`，序号从 1 起且仅在组内唯一 | `groupItemsOf()` |
+| 6 | 只有优先组 `defaultExpanded = true`；汇总项恒 `false` | `runSmartGroup()` 返回处 |
+| 7 | 业务对象只有三个键；诊断信息只能在 `meta` | `finish()` + `planTodoOutput()` |
+| 8 | 所有 ID 一律 string；除计数类（`count`/`totalCount`）与标记类（`isremark`/`requestLevel`）外不得是 number | `readAiGroups()` 等校验 |
+| 9 | 子组至少 2 条（<2 解散后条目平铺）；不存在 `other` 兜底汇总项 | `runSmartGroup()` 子组收口 |
+
+## 7. 各 stage 的 `data` 形态不同（最易踩）
+
+| stage | `data` 的键 | 分组是最终态吗 |
+|---|---|---|
+| `collect` | `stage, query{…}, fetched, items[], wfIdGroup[], groupingBrief[], groupInfo, detailStats, warnings, markdown` | ❌ 中间态：`wfIdGroup[]` 用 `requestDatas` + `stats`，**没有** `displayItems` |
+| `group` | `stage, groupBy, smartSummaryTitle, totalInput, total, duplicateCount, groupCount, totals, wfIdGroup[], restTotal, restGroupCount, restGroups, warnings, markdown` | ❌ 同上 |
+| `smartGroup` | `smartSummaryTitle, totalCount, wfIdGroup[]`（+ 可选 `summaryBatches`/`summaryStats`） | ✅ 最终三键 |
+| `summaryContext` | 三键 + `summaryBatches` + `summaryStats` | ✅ |
+| `summary` | 三键（统计在 `meta`） | ✅ |
+| `groupSummaryContext` | 三键 + `groupSummaryBatches` + `groupSummaryStats` | ✅ |
+| `groupSummary` | 三键（统计在 `meta`） | ✅ |
+| `aggregate` | `groupBy, totalInput, total, duplicateCount, groupCount, totals, groups, restGroups, warnings, markdown` | ❌ 旧兼容结构，**不产三键** |
+
+> 只有 `smartGroup` 之后才是前端要的 `Comp.WflTodoSummary` 载荷；`collect` 的 `wfIdGroup` 直接拿去渲染会缺 `displayItems`。
+
+## 8. 回灌输入契约
+
+- `stage` 显式优先；**三键结构里故意不带 `stage`**，未传时按入参形态推断：
+
+| 入参形态 | 推断结果 |
+|---|---|
+| 有 `wfIdGroup` + 有 `aiGroupSummaries` | `groupSummary` |
+| 有 `wfIdGroup` + 有 `aiSummaries` | `summary` |
+| 有 `wfIdGroup`，且已有非空单条 `summary` | `groupSummaryContext` |
+| 有 `wfIdGroup`，单条摘要全空 | `summaryContext` |
+| 其它 | `auto` |
+
+- 输入字段白名单 `assertKnownKeys`，多一个键 → `input_unknown_key` 硬失败。
+- ⚠️ **`items` 必须带 `workflowName`**：分组键取的是 `workflowName`，不是 `workflowId`。实测漏传时 4 个不同工作流全部塌进「未分类」一组（`id` 还会回落成第一条的 `workflowId`）。
+- `aiGroups` 每项只允许 `groupId` / `title` / `requestIds`（与 `seq` 二选一）；`priority` 组不可二次分组。
+- `aiSummaries` 每项只允许 `requestId` / `summary`；`aiGroupSummaries` 每项只允许 `groupId` / `summary`（用汇总项 id，不是父组 id）。
+
+## 9. 摘要字段的填充规则（三处语义不同）
+
+| 阶段 | 行为 |
+|---|---|
+| `summaryContext` | 详情为空的条目**不喂 AI**，CLI 直接把 `requestNameTitle` 写进 `summary`（确定性兜底） |
+| `summary` | 只写 `aiSummaries` 里给的；**漏写保留空串，不拿标题凑**；已有的标题/缓存摘要会被保留 |
+| `groupSummary` | 只填 `displayItems[].summary`；确定性路径（请假 / 财务 / 客户问题支持）的固定文案**不会被覆盖** |
+
+满意度类不走 AI：单条 `summary` 直接用 `requestNameTitle` 兜底（**不留空串**）。
+
+摘要缓存**只省 AI，不省详情**：命中摘要缓存的条目仍会按 `requestId__lastFeedBackDateTime` 查详情缓存（命中则零请求），因为阈值指标只认流程详情数据。
+
+## 10. 错误码（`ok:false` + `error.subtype`）
+
+| 错误 | 含义 |
+|---|---|
+| `stage_invalid` / `input_unknown_key` | stage 或输入字段不合法 |
+| `items_required` / `items_invalid` / `items_too_many` | 缺 items / 形态错 / 超 500 条 |
+| `ai_groups_invalid` | aiGroups 结构、字段、seq 类型不合法 |
+| `ai_group_unknown_group` | groupId 不在本次分组结果中 |
+| `ai_group_priority_unsupported` | 想给优先组做二次分组 |
+| `ai_group_seq_out_of_range` | seq 越界 |
+| `ai_group_unknown_request` / `ai_group_duplicate_request` | 条目不存在 / 被分进多个子组 |
+| `ai_groups_required` | **内部留言 ≥3 条缺本组计划**：硬失败（`retryAllowed:true`），报错带 `groupId` 与 `1..N` 序号；非内部留言的类型不适用此错误 |
+| ~~`ai_groups_missing_group`~~ | **已删除（2026-10-27）**：非内部留言的类型「意图适用但没给计划」改为「视为无意图 + warning」 |
+| `ai_summaries_required` / `ai_summary_invalid` | 缺回填数据 / 结构错 |
+| `ai_summary_duplicate_request` / `ai_summary_unknown_request` | 重复 / 未知 requestId |
+| `ai_group_summaries_required` / `ai_group_summary_unknown_group` | 同上，按汇总项 id |
+| `final_groups_required` / `wfidgroup_invalid` | 缺最终结构 / 结构不合法 |
+| `forbidden_endpoint` | 取数阶段误调了 `getTodo*` 其它接口 |
+
+## 11. 示例（合成数据，按 2026-10-27 规则构造：5 条 / 3 组，`withDetailContext:false`）
+
+```json
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "operation": "workflow.todoSmartConvert",
+  "data": {
+    "smartSummaryTitle": "您当前有 5 条待办，清单如下：",
+    "totalCount": 5,
+    "wfIdGroup": [
+      { "id": "priority", "topPriority": true, "title": "建议优先处理的流程", "count": 1,
+        "defaultExpanded": true,
+        "displayItems": [{ "type": "request", "requestData": { "requestId": "8800000000000000001", "…": "共 14 个字段", "summary": "" } }] },
+      { "id": "1003", "topPriority": false, "title": "费用报销", "count": 4,
+        "defaultExpanded": false,
+        "displayItems": [
+          { "type": "group", "id": "1003-1", "title": "差旅报销", "count": 2,
+            "summary": "", "defaultExpanded": false, "requestDatas": [{ "…": "" }, { "…": "" }] },
+          { "type": "request", "requestData": { "requestId": "8800000000000000001", "…": "" } },
+          { "type": "request", "requestData": { "requestId": "8800000000000000005", "…": "" } }
+        ] },
+      { "id": "1001", "topPriority": false, "title": "内部留言", "count": 1,
+        "defaultExpanded": false,
+        "displayItems": [{ "type": "request", "requestData": { "requestId": "8800000000000000002", "…": "" } }] }
+    ]
+  },
+  "meta": {
+    "branch": "todo-smart-convert", "stage": "smartGroup", "aiGrouped": true,
+    "timing": { "stage": "smartGroup", "steps": [{ "name": "smartGroup", "kind": "cli", "durationMs": 4 }], "durationMs": 4 },
+    "warnings": [
+      "「建议优先处理的流程」筛出 1 条：超时 1 条 / 等级命中 1 条（两者都满足 1 条），等级口径=紧急（requestLevel=2）；这 1 条同时保留在各自工作流分组中（叠加视图：Σcount 会大于 totalCount，totalCount 按去重条数计 = 5）",
+      "withDetailContext=false：本次未拉取任何详情——请假/财务阈值改为按标题识别、跳过整组空判定，也不产 summaryBatches",
+      "「费用报销」按财务类 100元以内确定性汇总，其余条目平铺"
+    ]
+  },
+  "warnings": []
+}
+```
+
+`totalCount = 5`，但 Σ`count` = 1 + 4 + 1 = **6**：那条超时件（`8800000000000000001`，属于"费用报销"）同时在优先组和"费用报销"组里各出现一次。组顺序是「优先组 → 费用报销 → 内部留言」，普通组按源数据首次出现顺序排列，优先条目不再被剔除。
+
+构造要点（对齐当前规则）：
+- 子组 `差旅报销` 是 **2 条**（≥2 才成立；1 条会被解散成单条）；
+- 阈值组之外的 2 条是**单条**（`type:"request"`），不是 `other` 汇总项；
+- `内部留言` 只有 1 条（<3 硬门槛），所以平铺单条、不给它汇总项。
+
+## 12. review 时值得盯的五个点
+
+1. **顶层 `warnings` 恒空**：`finish()` 把告警同时写进 `WorkflowEnvelope.warnings` 和 `meta.warnings`，但 `workflow/index.ts` 的 `successEnvelope()` 硬编码 `warnings: []`，前者被丢弃。任何「有没有告警」的判断都必须看 `meta.warnings`。要么删掉信封级字段，要么让它透传。
+2. **`requestData` 里混进了技术字段 `lastFeedBackDateTime`**：它现在是**摘要缓存 + 详情缓存**共同的 key 组成部分（`requestId__lastFeedBackDateTime`），前端渲染不需要。是否应该留在业务对象里值得确认——但注意删掉它会让两个缓存都失去「流程一动就换键」的能力。
+3. **「未分类」组的 `id` 可能等于某个真实 `workflowId`**：`group.ts` 里 `id = row.workflowId || name:${key}`，所以当 `workflowName` 缺失时，这一组的 `id` 会回落成该组第一条的 workflowId。二次分组传 `groupId` 时容易与真实工作流组混淆。
+4. **与前端 mock 目标的差异**（`docs/todo-smart-convert/mock/ai-todo-query-target.json`）：mock 的 `requestData` 带 `requestNameHtml`，实际输出**没有**这个字段；mock 里 ID 是数字，实际是字符串。若前端组件依赖 `requestNameHtml`，需要回退到 `requestNameTitle`。
+5. **详情请求的耗时从 `summary` 挪到了 `smartGroup`**：冷缓存下 `smartGroup` 承担全部详情请求（近一年 77 条 = 77 次 `/getWorkflowRequest`），`summary` 阶段实测 **0 请求**（12ms）。所以看 `meta.timing` 时别再用「`summary` 阶段请求数」判断有没有拉详情，要看 `smartGroup` 的 `summaryStats.detailNetworkFetched` / `detailFetchStats`。