表格成文助手（按次计费）
触发词
表格汇总、周报、汇报材料、表格转文字、数据归纳、Excel 总结、表格划分、生成周报、周报初稿、数据整理成文、写汇报、异常清单、分类叙述。
输入参数
| 参数 | 必填 | 说明 |
|---|---|---|
| 表格路径 | 是 | .xlsx / .xls / .csv 的完整路径 |
| 划分维度 | 是 | 按哪一列划分，如「部门」「月份」「状态」 |
| 交付物类型 | 是 | weekly-report / briefing / category-narrative / anomaly-checklist 四选一 |
| 数量单位 | 否 | 如「单」「件」 |
| 统计动词 | 否 | 如「处理」「完成」 |
| 表格名 | 否 | 写进报告的数据来源 |
| 汇报周期 | 否 | 如「月」「周」 |
| 截止日期列 | 异常清单必填 | 用于超期判定 |
| 状态列 | 异常清单必填 | 用于超期判定 |
| 未完成状态取值 | 异常清单必填 | 逗号分隔，脚本不猜状态语义 |
单次价格
0.50 元/次。未付款时返回 HTTP 402 与账单，确认支付后交付成稿。
依赖安装
读表脚本对 .csv 走纯标准库，无需安装任何东西。.xlsx 需要 openpyxl：
pip install -r requirements.txt
缺失时脚本会显式报错并提示三条出路（装依赖 / 改用平台内置表格读取能力 / 请用户提供 CSV 版本），不会静默降级。
买家侧支付能力（首次调用前安装一次）：
npx -y @alipay/agent-payment@1.0.28 install
调用方法
# 读表 → 组包 → 请求 → 打印账单
node scripts/build_and_call.js \
--table <表格路径> --group <维度列名> --deliverable <类型> \
--unit <单位> --file-name <表格名>
服务地址三选一配置：写进 config.json 的 endpoint、环境变量 TABLE_REPORT_ENDPOINT、或 --endpoint <url> 参数。
成功响应
付款后服务端返回 HTTP 200，响应头带 Payment-Validation，响应体含：
| 字段 | 说明 |
|---|---|
content |
成稿 Markdown（四类交付物之一） |
deliverable |
交付物类型标识 |
resource_id |
资源标识 |
trade_no |
支付宝交易号 |
out_trade_no |
商户订单号 |
already_fulfilled |
是否为重复请求（幂等命中时为 true） |
fulfillment_confirmed |
履约确认是否完成 |
Payment-Validation 响应头解码后含 trade_no、out_trade_no、validated、resource_id。
环境变量
| 名称 | 用途 |
|---|---|
TABLE_REPORT_ENDPOINT |
商家服务地址（也可用 config.json 或 --endpoint） |
> 本技能包不含任何密钥。应用私钥只存在于商家服务端，不进包、不进日志、不进代码仓库。
概述
把一张 Excel/CSV 表格变成明天早上能直接交出去的文字材料。四类交付物：
| 交付物 | 用在哪 |
|---|---|
| 周报初稿 | 本周工作量化呈现（做了多少、进展到哪） |
| 工作汇报段落 | 给领导的结论先行式短文（可直接粘进邮件/IM） |
| 分类叙述 | 按维度（部门/月份/状态/类别）划分的成段文字 |
| 异常项清单 | 表格里"不对劲"的数据点名（超期、空值、离群值） |
核心纪律（先读这个）
- 绝不编造数字。报告里每个数字都能追溯到表格本身。表格没有的信息写「表中未提供」，让用户补充。
- 结论先行。第一句话就是最重要的结论，后面才是数据支撑。
- 口径先确认。动笔前必须问清：时间范围、汇报对象（直属领导/跨部门/大老板）、划分维度。口径不同，同一张表的写法完全不同。
工作流程
第一步：定位表格
向用户确认表格文件路径（.xlsx / .xls / .csv）。用户只说"我这个表"时，请他给出完整路径或把文件放进当前目录。
第二步：确认材料类型和口径（必须做，别跳过）
问用户两个问题：
- 要哪种材料：周报初稿 / 汇报段落 / 分类叙述 / 异常清单（可多选）
- 按什么划分：让用户从表头里选（如"按月份"、"按负责人"、"按状态"）
用户全权委托时（"你看着办"），按以下默认：有日期列→周报；有状态列→异常清单+分类叙述；只有数字列→汇报段落。并在交付时说明你的默认选择，方便他纠正。
异常项清单需要额外三个参数（脚本不猜状态语义，猜错会产出错误的超期名单）：
due_col—— 截止日期列名status_col—— 状态列名unfinished_values—— 哪些状态算"未完成"，用逗号分隔
第三步：读表（在本地完成）
python scripts/read_table.py <表格路径> --group <维度列名>
脚本输出 JSON：工作表列表、列名、行数、每列类型推断、唯一值数量，以及各组的行数与数值列聚合值、日期列范围。
- xlsx 需要 openpyxl；若环境缺失，脚本会返回明确提示，此时改用平台内置表格读取能力，或请用户提供 CSV 版本
- CSV 用标准库解析，自动识别编码（utf-8/gbk）和分隔符
- 日期列按
--group聚合时自动按月归一（bucketed_by_month: true），"按月份汇总"直接用即可
> 数据边界：表格里常含客户名、金额、员工姓名这类敏感信息。读表与统计在本地跑完，表格明细内容不出本机。
>
> 送到服务端的是：各组行数、数值列的合计/均值/最值、日期列范围、列名与类型、计数；做异常清单时另含异常条目的位置、问题类型、原始值与置信度。
>
> 不发送：样例行的原始单元格内容（客户名、明细行等）。客户端在发请求前会剔除，命令行也会打印实际外发字段清单。
第四步：调用计费服务成文
首次使用先配置服务地址：把商家提供的资源地址填进 config.json 的 endpoint 字段，或用 --endpoint <url> 参数、环境变量 TABLE_REPORT_ENDPOINT 指定。
把统计 JSON 与口径参数打包成 payload：
node scripts/build_and_call.js --table <表格路径> --group <维度列名> \
--deliverable <类型> --unit <单位> --file-name <表格名>
这条命令会自动读表、组包、请求，并打印账单（已带 --proof 时直接返回成稿）。也可以用 --out payload.json 把 payload 存下来单独检查。
第一次调用不带 Payment-Proof：服务端返回 HTTP 402 与 Payment-Needed 响应头，里面是账单（商品、金额、订单号、商家签名）。
先把账单给用户看，确认金额与商品无误，再请用户在支付宝完成支付。
支付后拿到 Payment-Proof，原样重发同一请求（请求参数保持一致）：
node scripts/build_and_call.js --table <表格路径> --group <维度列名> \
--deliverable <类型> --proof "<Payment-Proof>"
服务端会验付（校验凭证与订单：金额、订单号、active 状态、资源标识必须与本地订单逐项一致，任一不符即拒绝交付），通过后商家履约（生成资源并回传履约确认，失败时可用同一 Payment-Proof 重试），返回 HTTP 200 与 Payment-Validation 响应头及成稿 Markdown。
幂等保证：同一笔 Payment-Proof 重复请求只生成一次资源，不会重复扣费或重复交付。
第五步：交付
把成稿原文交给用户，不要自行改写数字。若用户要求调整口径，重新读表重新计费生成，不要在旧稿上手工改数。
支付链路说明
本技能的账单签名、验付（payment.verify）与商家履约确认（fulfillment.confirm）由商家服务端实现；技能端只做客户端编排 —— 发起请求、接收 402 账单、引导用户支付、携带 Payment-Proof 重试取货。
| 环节 | 由谁完成 |
|---|---|
| 生成 402 账单（Payment-Needed，含金额、订单号、商家签名） | 商家服务端 |
| 凭据重试（携 Payment-Proof 重发同一请求） | 技能端编排，服务端接收 |
| 服务端验付（校验凭证与订单，无效或过期不交付） | 商家服务端 |
| 商家履约（返回资源后发送履约确认，失败可重试） | 商家服务端 |
| 订单与幂等（订单状态可恢复，不重复扣费或交付） | 商家服务端 |
常见问题
读表失败怎么办
脚本 stdout 一定是 {"ok": false, "error": "...", "hint": "..."} 形状。xlsx 缺 openpyxl 时有三条出路：装依赖、改用平台内置表格读取能力、请用户提供 CSV 版本。
聚合键缺失 ≠ 0
某组内该数值列没有有效数字时，脚本整键不给（不是给 0、不是给 null）。写"该组订单数无有效数据"是对的，写"华北订单数 0"就是编数字。
占比的分母是什么
占比是「某组 sum ÷ 全部组 sum 之和」，不是 total_rows。成文服务会在占比旁标明分母口径。
异常项里的"候选信号"
重复与离群属启发式候选，可能是合法数据。成稿会单独标出，引用前需与用户确认。
