weaver-work-cli 0.1.8 → 0.1.20

package/skills/weaver-e10-yepiaotong/references/invoice-output-view.md

@@ -0,0 +1,135 @@
+# 发票输出投影与渲染（--format / --view / --fields）
+
+## 什么时候读取
+
+用户要**查询票夹、看发票清单、按条件筛票**，或者需要把发票列表交给用户阅读时读取本文件。
+
+不读本文件的场景：写操作（导入/新增/编辑/删除/报销填单）——这些按各自 reference 处理；单张发票详情见 `invoice-detail.md`。
+
+## 三层出口：渲染档 / 语义视图 / 点路径投影
+
+| 出口 | 用途 | 输出形态 |
+|---|---|---|
+| `--format markdown` | **要在对话里展示给用户时首选** | markdown 文本（表格/卡片），非 JSON |
+| `--view summary`（列表）/ `--view detail`（`invoice.get`） | 要给程序消费的语义化数据 | JSON envelope，字段口径已固化 |
+| `--fields a,b.c` | 精确控制字段或用于无视图的 operation | JSON envelope，保持原嵌套 |
+
+三者的取舍：**给人看 → `--format markdown`；给下游代码看 → `--view`；只在特殊字段需求下才用 `--fields`。**
+
+## 为什么需要投影
+
+`invoice.list` / `invoice.enterprise.list` 的默认输出是**面向程序的完整包络**：单条发票 40+ 字段（`custom_field_*`、`oa`、`suser`、`rb`、`agricultural_*` 等），10 条约 35KB，而真正要看的只有 8 个字段（约 3KB）。
+
+**不要**因此自己现写解析脚本，也不要把完整 JSON 贴给用户。CLI 已原生提供上面三层出口。
+
+## 首选展示：`--format markdown`
+
+一次调用直接得到可读表格，列顺序、千分位、票种简称、挂单状态都已内置：
+
+```bash
+weaver-work-cli invoice list --format markdown
+weaver-work-cli invoice get --fid 1310817108299735054 --format markdown
+```
+
+票夹列表渲染为标题行（票夹口径 + 总数 + 合计金额）+ 8 列表格；发票详情渲染为「标头 + 字段表」（含附件、费用说明、开票人、查验标记）。
+
+规则：
+
+- **自带字段口径**，不必也不能再传 `--view`（`invoice.list` 固定 summary、`invoice.get` 固定 detail）；传了不一致的视图返回 `validation/input_conflict`
+- **与 `--fields` 互斥**（要自定义字段就用 `--fields` 出 JSON）
+- **与全局 `--json` 互斥**：markdown 是渲染档不是数据档，同时传返回 `validation/input_conflict`，提示去掉 `--json`
+- 只支持 `invoice.list` / `invoice.enterprise.list` / `invoice.get`；其他 operation 返回 `validation/format_unsupported`
+- 仍要自行拼表时用下面的 `--view`，不要退回完整 JSON
+
+### 拿到输出后怎么展示：贴进正文，别包代码围栏
+
+`--format markdown` 产出的是 **markdown 源码字符串**，表格、加粗、可点链接都要靠消费端的 markdown 渲染器解析。因此 Agent 拿到后要把它**作为消息正文原样输出**：
+
+- **不要用代码围栏（三个反引号）包裹**：围栏的语义是「原样照录、不解析」，包上就退化成等宽纯文本 —— 发票号码的链接变死文本、表格散架，等于把渲染档降级回 plaintext。
+- **不要改写、不要重新拼表**：CLI 给的就是成品，转录要保真；别自行加反斜杠转义（把 `*` 写成 `\*`）、别调整字符或列顺序。
+- 在终端里直接执行只能看到源码，这属正常；要预览渲染效果，用支持 markdown 的客户端（浏览器、聊天界面），或在本地用 markdown 渲染器（如 `glow`、`mdcat`）。
+
+## 语义视图：`--view summary`（列表）/ `--view detail`（详情）
+
+`--view summary` 给出语义平表，字段口径与 `invoice.reim.candidates.list` 的 items 一致。
+
+字段集（**省略空值**，所以某条票可能少几个键）：
+
+| 字段 | 含义 |
+|---|---|
+| `fid` | 发票主键，也是详情页跳转参数 |
+| `number` / `code` | 发票号码 / 代码 |
+| `typeName` | 票种名称，如"电子发票（增值税专用发票）" |
+| `date` | 开票日期 |
+| `amount` / `total` / `taxAmount` | 不含税金额 / 价税合计 / 税额 |
+| `buyer` / `buyerTaxNo` | 购买方名称 / 税号 |
+| `payer` / `payerTaxNo` | 销售方名称 / 税号 |
+| `valid` | 查验状态原始值（`1`=已查验） |
+| `status` | 发票状态原始值 |
+| `reimState` | 票面 `comm_info.pro.sreim` 原始值，**语义未定义，不要自行解读** |
+| `reimRequests` | 关联报销单名称数组，空数组表示未挂报销单 |
+| `fileName` | 附件文件名 |
+| `detailUrl` | 发票详情页链接，展示时必须转成可点击超链接 |
+
+列表级字段：`total`（票夹总数）、`totalAmount`（价税合计）、`totalAmountExcludingTax`、`hasMore`、`scope`、`itemCount`（本次返回张数）。
+
+`--view summary` 只对 `invoice.list` 与 `invoice.enterprise.list` 生效；`invoice.get` 用 `--view detail`（见 `invoice-detail.md`，在 summary 字段上多出 `attachments` / `expenseNote` / `issuer` / `checkState`）。对其他 operation 传视图参数会返回 `validation/view_unsupported`，此时改用 `--fields`、`--format markdown`（若该 operation 有模板）或默认完整输出。
+
+## 备用：`--fields` 点路径投影
+
+需要精确控制字段（例如只要号码和金额），或用于非列表 operation 时使用。点路径按**原始 JSON 结构**书写，输出保持原嵌套形状。
+
+- 作用于 `data.items` 数组时逐项投影，列表级汇总字段（`total` / `hasMore` 等）原样保留
+- 作用于其他 operation 时投影 `data` 本身
+- 未命中的路径出现在 `meta.projection.missingFields`；**全部**未命中时返回 `validation/field_not_found`
+- 与 `--view` **互斥**，同时传返回 `validation/input_conflict`
+
+> ⚠️ **`--fields` 里不要写裸 `total` 取金额。** 发票对象顶层的 `total` 是 E10 的独立字段（实测恒为 `0`），**价税合计在 `comm_info.price.total`**，不含税金额在 `comm_info.price.amount`，税额在 `comm_info.price.dtax`。要金额就用 `--fields comm_info.price.total`，或直接用 `--view summary`（那里的 `total` 已是价税合计）。
+
+三个参数都不属于 operation 的 `inputSchema`，它们只裁剪/渲染输出、不改变任何请求参数，因此不违反"列表查询不支持字段"的白名单校验。
+参数错误会在**发起业务请求之前**就返回（`view_unsupported` / `view_invalid` / `format_unsupported` / `format_invalid` / `input_conflict`），不会先打一次网络请求；只有 `field_not_found` 需要拿到结果才能判断。
+
+## 回执：`meta.projection`
+
+投影过的响应会在 `meta.projection` 里说明本次裁剪：
+
+```json
+{
+  "meta": {
+    "status": "COMPLETE",
+    "projection": { "view": "summary", "omittedEmpty": true }
+  }
+}
+```
+
+出现 `missingFields` 说明字段名写错了，按提示改正后重试，不要在缺失字段上继续加逻辑。
+
+## 兜底：CLI 版本低于 0.1.17
+
+旧版 CLI 没有 `--view` / `--fields` / `--format`（可用 `weaver-work-cli --version` 确认）。此时用随本 reference 提供的脚本 `invoice-summarize.py`，字段口径与 `--view summary` 完全一致：
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice list > list.json
+python3 ~/.workbuddy/skills/weaver-e10-yepiaotong/references/invoice-summarize.py list.json
+python3 ~/.workbuddy/skills/weaver-e10-yepiaotong/references/invoice-summarize.py list.json --format table
+weaver-work-cli --json invoice list | python3 ~/.workbuddy/skills/weaver-e10-yepiaotong/references/invoice-summarize.py -
+```
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice list | Out-File -Encoding UTF8 list.json
+python "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong\references\invoice-summarize.py" list.json
+python "$env:USERPROFILE\.workbuddy\skills\weaver-e10-yepiaotong\references\invoice-summarize.py" list.json --format table
+```
+
+脚本要求 Python 3，只用标准库；输入接受完整 envelope、`data` 对象、`{items:[...]}` 或 E10 原生 `{infos:[...]}`；`--format table` 输出 markdown 表格，适合直接贴给用户。
+
+## 注意事项
+
+- **发票号码必须用 `detailUrl` 渲染成可点击超链接**，格式为 `[号码](detailUrl)`；`--view summary` 已保留该字段，`--fields` 时记得把它列进字段表，否则详情链接会丢失。
+- 需要完整票面字段（`ext` 里的商品明细、`flist` 附件列表等）时不要用投影，走 `invoice.get`。
+- 统计金额以 `totalAmount` / `totalAmountExcludingTax` 为准，不要用单条 `total` 相加去"复核"服务端汇总——两者口径可能不同（作废票、红冲票的处理方式未在契约中定义）。
+- `reimState` 与列表筛选参数 `sreim` **不是同一套语义**：`sreim` 是筛选入参（`"0"`=全部、`"1"`=报销中、`"2"`=报销完成、`"3"`=未报销、`"4"`=不可报销），而票面 `comm_info.pro.sreim` 的取值含义未在 CLI 契约里定义，只能原样呈现。

package/skills/weaver-e10-yepiaotong/references/invoice-personal-list.md

@@ -16,8 +16,8 @@
 
 - `page_size`、`start_pos`
 - `content`
-- `date_begin`、`date_end`
-- `create_tm_begin`、`create_tm_end`
+- `date_begin`、`date_end`（开票日期含当日）
+- `create_tm_begin`、`create_tm_end`（创建时间含当日）
 - `payer_company`、`buyer_company`
 - `payer_taxno`、`buyer_taxno`
 - `code`、`number`
@@ -39,6 +39,8 @@ Windows PowerShell：
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"content":"滴滴"}'
 
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"sreim":"2"}'
+
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"date_begin":"2026-09-01","date_end":"2026-09-30"}'
 ```
 
 macOS/Linux（bash/zsh）：
@@ -47,12 +49,22 @@ macOS/Linux（bash/zsh）：
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"content":"滴滴"}'
 
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"sreim":"2"}'
+
+weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0,"date_begin":"2026-09-01","date_end":"2026-09-30"}'
 ```
 
 ## 返回
 
-返回 `items`、`total`、`totalAmount`、`totalAmountExcludingTax`、`hasMore` 和 `scope="personal"`。分页时递增 `start_pos`，保持筛选条件和排序不变。
+返回 `items`、`total`、`totalAmount`、`totalAmountExcludingTax`、`hasMore` 和 `scope="personal"`。每条 item 包含 `detailUrl`（如 `https://xxx/sp/inc/incDetail?fid=<fid>`）。分页时递增 `start_pos`，保持筛选条件和排序不变。
+
+向用户展示发票列表时，**发票号码必须用 markdown 链接格式** `[号码](detailUrl)` 展示，让用户点击直接打开发票详情页。
 
 ## 注意
 
 不要在输入里传 `flag`；即使传入也会被 CLI 忽略并固定为个人票夹。空筛选条件直接省略，不要把空字符串传给 integer 字段。除非用户明确要求全部或某个报销状态，否则不要传 `sreim`；除非用户明确要求凭证，否则不要传 `bill_type`。
+
+**时间字段两种写法都接受**（0.1.15 起）：`date_begin`/`date_end`/`create_tm_begin`/`create_tm_end` 既可以传 `"YYYY-MM-DD"`（按东八区零点换算），也可以传秒级时间戳 integer（E10 `/api/inc/sync` 的原生格式）。CLI 会在本地归一，非法值直接报 `validation/input_invalid`，不会再透传到 E10 变成不透明的 `400 系统错误`。`page_size`/`start_pos`/`req_type`/`mask`/`mext` 同样会归一：数字串（如 `"20"`）可以，`"abc"`、`-1`、`1.5` 会被本地拦下。
+
+> 0.1.14 及更早：CLI 不做本地归一，字符串日期会一路透传到 E10 并返回 `api/business_error`/`400 系统错误`。用 `doctor --e10` 的 package 字段确认版本。
+
+> `invoice.reim.candidates.list` 的 `date_begin`/`date_end` 同样接受 `YYYY-MM-DD` 或秒级时间戳，与 `invoice.list` 口径一致。

package/skills/weaver-e10-yepiaotong/references/invoice-reim.md

@@ -25,7 +25,7 @@
 3. 用 `invoice.reim.requests.list` 获取事前申请，再按时间、费用类型和标题做匹配；原始 ID、日期、金额必须逐字符保留。
 4. 用 `invoice.reim.workflow.resolve` 得到报销工作流，必要时按工作流分组。
 5. 对每组并行读取 `invoice.reim.form.structure`、`invoice.reim.row-info` 和 `invoice.reim.employee-superiors`；只有需要用户修正关联字段时才用 `invoice.reim.field.search`。
-6. Agent 按表单结构组装报销单 JSON，先调用 `invoice.reim.flow.create.prepare`，展示标题、主表字段数、明细行数、发票和风险；用户明确确认后再调用 `.apply`。
+6. Agent 按表单结构组装报销单 JSON，先调用 `invoice.reim.flow.create.prepare`，展示标题、主表字段数、明细行数、发票和风险；用户明确确认后再调用 `.apply`。命中「话费补贴标准审批流程」或「话费报销」时，必须先读 [`reim-phone-subsidy-rules.md`](reim-phone-subsidy-rules.md)，按月度标准核算实报金额，不能直接用发票金额填单。
 7. 报销单创建成功后，后续修正使用 `invoice.reim.flow.update.prepare/apply`，不要重复创建同一组发票的报销单。
 
 ## 命令

package/skills/weaver-e10-yepiaotong/references/invoice-summarize.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""把 weaver-work-cli 发票查询的完整 JSON envelope 裁成语义摘要。
+
+为什么需要它
+------------
+`invoice.list` / `invoice.enterprise.list` 的原始输出里，单条发票有 40+ 字段
+（`custom_field_*`、`rb`、`oa`、`suser`、`agricultural_*` 等对调用方无用），
+10 条就是 35KB 左右。要拿到"号码 / 金额 / 购销方"就得先解析一遍。
+
+优先用 CLI 原生能力
+------------------
+CLI 0.1.17 起支持 `--view summary`（语义平表）与 `--fields a,b.c`（点路径投影），
+Agent 应当优先用它们，不必写脚本：
+
+    weaver-work-cli --json invoice list --view summary
+
+本脚本用于以下兜底场景：
+  1. 目标机器上的 CLI 版本低于 0.1.17，没有 `--view summary`
+  2. 需要把结果整理成 markdown 表格直接贴给用户
+  3. 需要在多份导出文件之间做汇总核对
+
+用法
+----
+    weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10}' > list.json
+    python invoice-summarize.py list.json
+    python invoice-summarize.py list.json --format table
+    weaver-work-cli --json invoice list | python invoice-summarize.py -
+
+输入可以是：完整 envelope、`data` 对象、`{items:[...]}`，或 E10 原生 `{infos:[...]}` 响应。
+
+字段口径与 CLI `--view summary` 保持一致（见 references/invoice-output-view.md）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+# 与 src/shortcuts/invoice/projection.ts 的 SUMMARY_ITEM_FIELDS 保持同序同义
+SUMMARY_FIELDS = [
+    "fid",
+    "number",
+    "code",
+    "typeName",
+    "date",
+    "amount",
+    "total",
+    "taxAmount",
+    "buyer",
+    "buyerTaxNo",
+    "payer",
+    "payerTaxNo",
+    "valid",
+    "status",
+    "reimState",
+    "reimRequests",
+    "fileName",
+    "detailUrl",
+]
+
+TABLE_COLUMNS = [
+    ("number", "发票号码"),
+    ("typeName", "类型"),
+    ("date", "开票日期"),
+    ("total", "价税合计"),
+    ("payer", "销方"),
+    ("buyer", "购方"),
+    ("reimRequests", "关联报销单"),
+]
+
+
+def as_dict(value: object) -> dict:
+    return value if isinstance(value, dict) else {}
+
+
+def as_text(value: object) -> str:
+    if value is None:
+        return ""
+    return str(value).lstrip("\ufeff").strip()
+
+
+def as_int(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    return None
+
+
+def summarize_item(item: dict) -> dict:
+    """把一条原始发票对象裁成语义摘要；空值省键，票面自带的 '0' 保留。"""
+    comm = as_dict(item.get("comm_info"))
+    pro = as_dict(comm.get("pro"))
+    price = as_dict(comm.get("price"))
+    buyer = as_dict(comm.get("buyer"))
+    payer = as_dict(comm.get("payer"))
+    modify = as_dict(item.get("modify_info"))
+    oreim = as_dict(item.get("oreim"))
+    reim_list = oreim.get("list_reim") if isinstance(oreim.get("list_reim"), list) else []
+
+    summary = {
+        "fid": as_text(item.get("fid") or item.get("id")),
+        "number": as_text(item.get("number")),
+        "code": as_text(item.get("code")),
+        "typeName": as_text(pro.get("cname")),
+        "date": as_text(pro.get("date")),
+        "amount": as_text(price.get("amount")),
+        "total": as_text(price.get("total")),
+        "taxAmount": as_text(price.get("dtax")),
+        "buyer": as_text(buyer.get("company")),
+        "buyerTaxNo": as_text(buyer.get("tcode")),
+        "payer": as_text(payer.get("company")),
+        "payerTaxNo": as_text(payer.get("tcode")),
+        "valid": as_int(pro.get("valid")),
+        "status": as_int(pro.get("status")),
+        "reimState": as_int(pro.get("sreim")),
+        "reimRequests": [as_text(as_dict(entry).get("name")) for entry in reim_list if as_text(as_dict(entry).get("name"))],
+        "fileName": as_text(modify.get("fname")),
+        "detailUrl": as_text(item.get("detailUrl")),
+    }
+    return {key: value for key, value in summary.items() if value not in ("", None, [])}
+
+
+def extract_items(payload: object) -> tuple[list, dict]:
+    """兼容 envelope / data / items / E10 原生 infos 四种输入形状。"""
+    root = as_dict(payload)
+    data = as_dict(root.get("data")) or root
+    for key in ("items", "infos"):
+        candidate = data.get(key)
+        if isinstance(candidate, list):
+            return candidate, data
+    if isinstance(payload, list):
+        return payload, {}
+    return [], data
+
+
+def summarize_payload(payload: object) -> dict:
+    items, data = extract_items(payload)
+    summary = {}
+    for key in ("total", "totalAmount", "totalAmountExcludingTax", "hasMore", "scope"):
+        if data.get(key) is not None:
+            summary[key] = data[key]
+    summary["items"] = [summarize_item(as_dict(item)) for item in items]
+    summary["itemCount"] = len(summary["items"])
+    return summary
+
+
+def render_cell(item: dict, key: str) -> str:
+    value = item.get(key)
+    if key == "reimRequests":
+        names = value if isinstance(value, list) else []
+        if not names:
+            return "-"
+        return names[0] if len(names) == 1 else f"{names[0]} 等 {len(names)} 笔"
+    return str(value) if value is not None else ""
+
+
+def render_table(summary: dict) -> str:
+    lines = []
+    header = "| " + " | ".join(label for _, label in TABLE_COLUMNS) + " |"
+    divider = "|" + "---|" * len(TABLE_COLUMNS)
+    lines.append(header)
+    lines.append(divider)
+    for item in summary["items"]:
+        cells = [render_cell(item, key) for key, _ in TABLE_COLUMNS]
+        lines.append("| " + " | ".join(cells) + " |")
+
+    parts = [f"共 {summary.get('itemCount', 0)} 张"]
+    if summary.get("total") is not None:
+        parts.append(f"票夹总数 {summary['total']}")
+    if summary.get("totalAmount") is not None:
+        parts.append(f"价税合计 {summary['totalAmount']}")
+    if summary.get("hasMore"):
+        parts.append("还有更多（hasMore=true）")
+    lines.append("")
+    lines.append("；".join(parts))
+    lines.append("")
+    lines.append("注：`reimState`（票面 `comm_info.pro.sreim`）的取值语义未在 CLI 契约中定义，只能原样呈现，不要自行解读成已报销/未报销。")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="把 weaver-work-cli 发票查询的完整 JSON 输出裁成语义摘要（CLI --view summary 的兜底方案）",
+    )
+    parser.add_argument("path", help="JSON 文件路径，或 - 表示从标准输入读取")
+    parser.add_argument("--format", choices=["json", "table"], default="json", help="json=摘要对象（默认），table=markdown 表格")
+    parser.add_argument("--indent", type=int, default=1, help="json 格式的缩进，默认 1")
+    args = parser.parse_args(argv)
+
+    if args.path == "-":
+        raw = sys.stdin.read()
+    else:
+        try:
+            with open(args.path, encoding="utf-8-sig") as handle:
+                raw = handle.read()
+        except OSError as error:
+            print(f"无法读取 {args.path}：{error}", file=sys.stderr)
+            return 1
+
+    try:
+        payload = json.loads(raw.lstrip("\ufeff"))
+    except json.JSONDecodeError as error:
+        print(f"{args.path} 不是合法 JSON：{error}", file=sys.stderr)
+        return 1
+
+    summary = summarize_payload(payload)
+    if args.format == "table":
+        print(render_table(summary))
+    else:
+        print(json.dumps(summary, ensure_ascii=False, indent=args.indent))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/skills/weaver-e10-yepiaotong/references/invoice-upload-and-validate.md

@@ -0,0 +1,88 @@
+# 一站式上传+OCR+查验
+
+## 什么时候读取
+
+用户要求上传发票附件并完成查验（上传→识别→查验一步到位）时读取本文件。
+如果用户只需要单独上传或单独 OCR，请分别参阅 `invoice-file-upload.md` 或 `invoice-import.md`。
+
+## Operation
+
+| Operation | 说明 |
+| --- | --- |
+| `invoice.upload-and-validate` | 上传发票文件 → OCR 识别 → 逐张查验，合并为单条命令 |
+
+## 输入参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `file` | string | 与 url 二选一 | 本地文件路径 |
+| `url` | string | 与 file 二选一 | 可访问的文件 URL |
+| `scope` | string | ✅ | `personal`（个人票夹）或 `enterprise`（企业票夹） |
+
+文件来源支持扩展名：`pdf`、`ofd`、`xml`、`png`、`jpg`、`jpeg`。
+本地文件必须存在、非空且不超过 25 MiB。URL 只允许 `http/https`，不能包含账号密码。
+
+## 示例
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.upload-and-validate --input-json '{"file":"./invoice.pdf","scope":"personal"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.upload-and-validate --input-json '{"file":"./invoice.pdf","scope":"personal"}'
+```
+
+## 返回
+
+```jsonc
+{
+  "status": "COMPLETE",
+  "data": {
+    "upload": { /* upload 对象：id, ids, fileType, fileName, totalPages … */ },
+    "ocrCount": 1,           // OCR 识别出的发票数量
+    "invoices": [ /* OCR 识别出的发票列表（原始 info） */ ],
+    "validations": [         // 每张发票的查验结果
+      {
+        "fid": "751293486469988353",
+        "code": "031001900311",
+        "number": "00188205",
+        "date": "2024-11-25",
+        "total": "200.00",
+        "buyer": "...",
+        "payer": "...",
+        "scope": "personal",
+        "validation": 1,      // 查验结果：1=真 0=假/未查验
+        "invoiceStatus": 0,
+        "saved": false
+      }
+    ],
+    "validationErrors": [],   // 查验失败的发票 [{fid, error}]
+    "results": [ /* OCR 原始返回 */ ],
+    "workflow": { "workflow": "invoice.upload-and-validate", "version": 1, "state": "COMPLETE" }
+  }
+}
+```
+
+### 部分失败
+
+- 上传失败：直接报错。
+- OCR 失败：返回 `partialData`（含 upload 对象），状态为 `OCR_FAILED`。
+- 单张查验失败：不中断整体流程，失败项记入 `validationErrors`，其余成功项正常返回 `validations`。
+
+## 与分步操作的关系
+
+本命令等价于依次执行：
+
+1. `invoice.upload`（上传文件获取 upload 对象）
+2. `invoice.ocr.preview`（OCR 识别所有页面）
+3. `invoice.validate.preview`（逐张查验）
+
+如需更细粒度的控制（例如只上传不查验、或重复 OCR），请使用上述分步命令。
+
+## 注意
+
+上传前必须先提醒用户：发票附件/图片/文件内容可能被上传到 E10 业票通，并可能进入当前大模型上下文用于理解和处理；只有用户明确确认后才执行。用户仅提供文件路径或文件名不等于同意上传。

package/skills/weaver-e10-yepiaotong/references/invoice-validation-preview.md

@@ -1,8 +1,13 @@
-# 查验预览
+# 查验预览（仅限已在票夹中的发票）
 
 ## 什么时候读取
 
-用户要查验已有发票，但没有明确要求把查验结果回写票夹时读取本文件。
+用户要查验**已在票夹中的发票**（已有 `fid`），但没有明确要求把查验结果回写票夹时读取本文件。
+
+## ⚠️ 路由判断
+
+- 如果用户提供的是**文件路径或 URL**（还没上传到票夹），**不要**使用本命令 → 应改用 `invoice.upload-and-validate`（一站式上传+OCR+查验）
+- 本命令**仅适用于票夹中已存在的发票**，必须已有 `fid`
 
 ## Operation
 

package/skills/weaver-e10-yepiaotong/references/reim-api-reference.md

@@ -104,8 +104,8 @@ CLI 已固定 `flag`（个人票夹=0 / 企业票夹=6），默认 `sreim="3"`
 | --- | --- | --- | --- |
 | `page_size` | Integer | 否 | 每页条数，默认 `10`，建议不超过 `20` |
 | `start_pos` | Integer | 否 | 分页起始位置，默认 `0` |
-| `date_begin` / `date_end` | Integer | 否 | 开票日期范围（**秒级时间戳**）。用户未指定日期时，默认最近一周 |
-| `create_tm_begin` / `create_tm_end` | Integer | 否 | 录入/创建日期范围（**秒级时间戳**），仅用户明确说录入/创建日期时使用 |
+| `date_begin` / `date_end` | Integer \| String | 否 | 开票日期范围。可传秒级时间戳，也可直接传 `"YYYY-MM-DD"`（0.1.15 起 CLI 按东八区零点换算）。用户未指定日期时，默认最近一周 |
+| `create_tm_begin` / `create_tm_end` | Integer \| String | 否 | 录入/创建日期范围，写法同上。仅用户明确说录入/创建日期时使用 |
 | `content` | String | 否 | 消费内容关键词（如 `"滴滴"`、`"住宿"`） |
 | `number` | String | 否 | 发票号码精确匹配 |
 | `types` | Array\<Integer\> | 否 | 发票类型 ID 数组（见下方映射表） |
@@ -115,6 +115,7 @@ CLI 已固定 `flag`（个人票夹=0 / 企业票夹=6），默认 `sreim="3"`
 ### 时间戳计算
 
 > **所有日期参数的秒级时间戳由 AI 按内联公式直接计算（UTC+8 时区）。**
+> 0.1.15 起 `date_begin` / `date_end` / `create_tm_begin` / `create_tm_end` 也直接接受 `"YYYY-MM-DD"`（CLI 按东八区零点换算），日期区间不跨时区歧义时优先写 `"YYYY-MM-DD"`，更省一次心算；需要精确到时分秒的边界（如 `23:59:59`）时才用秒级时间戳。
 > 完整公式和 Fallback 见 [reim-workflow.md - 时间戳内联计算](reim-workflow.md#时间戳内联计算零工具调用)。
 
 示例（最近一周，只传必要字段）：
@@ -427,6 +428,7 @@ weaver-work-cli --json invoice run invoice.reim.requests.list --input-json '{"pa
 
 - `cusCreateDateEnd` = 最晚发票 invoiceDate（事前申请不会晚于开票日期）
 - `cusCreateDateStart` = 最早发票 invoiceDate 往前推 90 天（合理的事前申请窗口期）
+- **话费报销例外**：话费补贴事前申请可能在很早以前审批，`cusCreateDateStart` 需往前推 **1095 天（3 年）**，并加 `requestname="话费"` 缩小结果。详见 [reim-phone-subsidy-rules.md](reim-phone-subsidy-rules.md)。
 
 ### 返回示例
 
@@ -869,14 +871,18 @@ weaver-work-cli --json invoice run invoice.reim.employee-superiors --input-json
       "id": "1201729946891231232",
       "name": "后端开发111"
     },
+    "directSuperior": {
+      "id": "1201729946891231233",
+      "name": "直属主管王五"
+    },
     "allSuperiors": [
       {
         "id": "1201729946891231111",
-        "name": "部门经理张三"
+        "name": "分管领导熊总"
       },
       {
-        "id": "1201729946891231222",
-        "name": "总监李四"
+        "id": "1201729946891231233",
+        "name": "直属主管王五"
       }
     ]
   },
@@ -890,16 +896,16 @@ weaver-work-cli --json invoice run invoice.reim.employee-superiors --input-json
 | --- | --- |
 | `currentEmployee.id` | 当前人员 ID（**字符串**，避免雪花 ID 超过 JS 安全整数精度） |
 | `currentEmployee.name` | 当前人员名称 |
-| `allSuperiors` | 所有上级列表（含直接上级和间接上级），每项含 `id` 和 `name` |
-| `allSuperiors[0]` | 第一个元素即为直接上级 |
+| `allSuperiors` | 所有上级列表（直接上级 + 间接上级，按层级从高到低排列），每项含 `id` 和 `name` |
+| `directSuperior` | **直接上级**（对象，含 `id` 和 `name`）。⚠️ **与 `allSuperiors[0]` 不是同一人**：`allSuperiors[0]` 是上级链中最高层（如分管领导），直接上级必须取 `directSuperior` |
 | `allSuperiors[].id` | 上级人员 ID（**字符串**） |
 
 ### 填单字段对应关系
 
 | 表单字段 | 取值方式 |
 | --- | --- |
-| 报销人上级 | `allSuperiors[0].id`（直接上级 ID，直接赋值） |
-| 承担人直接上级 | `allSuperiors[0].id`（直接上级 ID，直接赋值） |
+| 报销人上级 | `directSuperior.id`（直接上级 ID，直接赋值；**不是 `allSuperiors[0]`**） |
+| 承担人直接上级 | `directSuperior.id`（同上） |
 | 承担人所有上级 | `allSuperiors` 中所有 `id` 用逗号拼接（如 `"id1,id2,id3"`） |
 
 ---
@@ -969,6 +975,80 @@ weaver-work-cli --json invoice run invoice.reim.row-info --input-json '{"invoice
 
 ---
 
+## 5.6b 批量获取发票预填信息（0.1.19 新增）
+
+CLI operation：`invoice.reim.row-info-batch`
+
+一次调用获取多张发票的预填信息，内部并行处理（并发度 4），避免 Agent 逐张串行调用 `invoice.reim.row-info` 导致 N-1 次额外 CLI 启动与网络往返。
+
+### 入参
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `invoiceIds` | Array\<String\> | 是 | 发票 ID 列表，1-100 个 |
+| `requestid` | String | 否 | 事前申请流程 ID（无可不传或留空） |
+| `cdzt` | String | 否 | 当前用户/人员 ID，不传则 CLI 使用当前登录用户 |
+
+### 命令
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json invoice run invoice.reim.row-info-batch --input-json '{"invoiceIds":["1297093330645237792","1297093330645237793"]}'
+```
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json invoice run invoice.reim.row-info-batch --input-json '{"invoiceIds":["1297093330645237792","1297093330645237793"]}'
+```
+
+### 返回示例
+
+```json
+{
+  "results": [
+    {
+      "invoiceId": "1297093330645237792",
+      "status": "success",
+      "data": {
+        "date": "2026-07-29",
+        "fysm": "交通运输服务",
+        "itinerary": "1298798990831518001",
+        "subjectId": "100502270000000006"
+      }
+    },
+    {
+      "invoiceId": "1297093330645237793",
+      "status": "fail",
+      "error": "获取发票 1297093330645237793 行预填失败"
+    }
+  ],
+  "succeeded": 1,
+  "failed": 1,
+  "total": 2,
+  "workflow": { "workflow": "invoice.reim.row-info-batch", "version": 1, "state": "PARTIAL" }
+}
+```
+
+### 返回字段说明
+
+| 字段 | 说明 |
+| --- | --- |
+| `results[].invoiceId` | 对应的发票 ID |
+| `results[].status` | `"success"` 或 `"fail"` |
+| `results[].data` | 成功时返回，结构与单张 `row-info` 一致（`date`、`fysm`、`itinerary`、`subjectId`） |
+| `results[].error` | 失败时返回错误信息 |
+| `succeeded` / `failed` / `total` | 成功/失败/总数统计 |
+
+### 使用场景
+
+- **手工组装报销单时**（Step 3.5），用 `row-info-batch` 替代 N 次 `row-info` 调用
+- 部分失败不影响其他发票，失败的回退到 AI 推断逻辑
+- 快速路径（`template.build`/`auto-prepare`）内部已自带批量获取，无需额外调用
+
+---
+
 ## 5.7 获取发票详情（交通类发票行程信息）
 
 CLI operation：`invoice.get`