我做了一个根据销售 Excel 生成商品汇报的 Skill,逐步加上商品排名、退款处理、图表、日期分页和日志保存。功能能运行以后,一个更基础的问题反而变得重要:用户只上传了一张表,程序需要的 file_path、field_map 和退款口径,到底是谁准备的?
如果表头从“商品名称”改成“宝贝标题”,WorkBuddy 是否还能处理?既然已经有 schemas 文件夹,参数是不是会自动转换?又是哪一段代码让 WorkBuddy 先看表格?
这些问题对应不同环节。本文以我写的 product-sales-report 1.4 版为例,把一次任务从自然语言到报告文件的过程拆开说明。文中的目录和接口属于这套自定义实现,不代表 WorkBuddy 所有技能都必须采用同样的结构,也不假设它原生提供工作流节点或 ctx 接口。
1. 先用一张小表明确要算什么
假设业务提供了下面三条销售明细,金额单位为元,数量单位为件。这是本文构造的演示数据。
| 宝贝标题 | 本单实收 | 售出件数 | 售后标记 | 实际退回金额 | 实际退回件数 |
|---|---|---|---|---|---|
| 保温杯 | 200 | 5 | 未退款 | 0 | 0 |
| 咖啡豆 | 300 | 3 | 未退款 | 0 | 0 |
| 保温杯 | 120 | 3 | 部分退款 | 60 | 1 |
这里先约定一个关键前提:每行代表原销售明细,“本单实收”保存退款前的实收金额,退款额单独记录。 如果业务系统里的“本单实收”已经减过退款,下面的计算就不能直接套用。
按这个约定,预期结果是:
正向销售额 = 200 + 300 + 120 = 620 元退款金额 = 60 元净销售额 = 620 - 60 = 560 元净销量 = 5 + 3 + 3 - 1 = 10 件按商品汇总后,保温杯净销售额为 260 元,咖啡豆为 300 元。这套程序按净销售额排名,因此咖啡豆排在前面。
这个例子同时包含两个问题:程序需要知道“宝贝标题”是哪类字段,还需要知道退款应当如何扣减。前者是字段映射,后者是业务口径。只把表头识别对,还不足以保证计算正确。
2. 技能目录里的文件如何配合
这套技能的主要结构如下,省略了部分示例和测试文件:
product-sales-report/├── SKILL.md├── 使用说明.md├── requirements.txt├── schemas/│ ├── input.schema.json│ └── output.schema.json├── references/│ ├── data-contract.md│ ├── business-insights.md│ └── integration.md├── scripts/│ ├── sales_report.py│ ├── business_insights.py│ ├── report_charts.py│ ├── report_interactions.py│ ├── report_interactions.js│ ├── run_log.py│ ├── run_log.mjs│ └── workflow_adapter.mjs├── examples/└── output/SKILL.md 是给 AI 看的任务说明。它交代适用场景、处理顺序、统计口径和交付要求。使用说明.md 面向使用者,requirements.txt 声明 Python 依赖。
其余目录可以按下面的分工理解:
| 目录 | 作用 |
|---|---|
schemas | 声明输入、输出有哪些字段,以及类型和取值约束 |
references | 保存详细业务规则、参数说明和集成示例 |
scripts | 执行读表、校验、计算、报告生成和日志保存;测试也放在这里 |
examples | 提供销售样例、参数样例和示例报告 |
output | 常用的运行产物目录;报告位置由 output_dir 指定,并非固定只能写这里 |
例如,想改退款计算规则,应查看 sales_report.py;想改善业务提示,应查看 business_insights.py;想调整日期分页和图表切换,应查看 report_interactions.js。
目录存在本身不会触发任何动作。参考文档需要被读取,脚本需要被调用,Schema 也需要有程序使用它,才能在执行过程中发挥作用。
3. 谁让 WorkBuddy 先读表
在当前技能的 SKILL.md 中,执行步骤的第一条是:
确认销售文件、表头所在行和统计范围。用户已说明的条件直接沿用。表头有多个金额候选(如原价与实付),先确定口径,再用
field_map明确映射。
这段文字是在指导 WorkBuddy 组织任务。WorkBuddy 采用技能后,需要通过可用的文件处理工具或脚本取得表格内容,才能判断列的含义。模型不会仅凭文件名就知道每个单元格里是什么。
这里有两次可能发生的“读表”:
| 阶段 | 目的 | 执行者 |
|---|---|---|
| 正式统计前的查看 | 确认工作表、表头、样例内容和统计口径 | WorkBuddy 调用可用工具 |
| 正式统计时的读取 | 读取本次工作表的数据,逐行清洗并汇总 | Python 中的 _load(),Excel 读取使用 openpyxl |
预览可以只看少量样例,正式汇总则应覆盖本次选定工作表的数据,不能把样例行当成整张表。
当前 1.4 版的说明还没有把“先预览,再为陌生表头生成映射”写成完整的固定步骤。 它要求确认表头,但不能据此声称,每次执行都会自动识别所有陌生列名。Python 中也没有一个调用大模型来理解表头的函数。
如果要强化这一行为,可以把技能说明补充为下面这样的步骤。这是改进示例,不是当前版本已经加入的能力:
1. 正式统计前,使用可用工具列出工作表,读取候选表头和少量样例行。2. 确认表头所在行,区分商品、金额、数量、日期和退款相关列。3. 根据已确认的含义生成 field_map,映射值必须来自真实表头。4. 多个金额列含义不同或退款口径不清楚时,先确认业务含义。5. 将映射和统计配置写成 JSON,调用统计脚本。6. 检查返回结果、字段映射日志和异常明细,再交付报告。这样的说明让任务更明确,但仍然属于模型要遵循的指令。如果某个步骤必须被程序强制保证,还需要增加可检查的预检结果和后续校验,不能只依赖一段提示文字。
4. Schema、工作流参数和 Excel 表头是三件事
最容易混淆的是:“工作流里的参数,怎么变成 Schema 要的参数?”
准确地说,是调用方按照 Schema 描述的格式,构造一个输入对象。Schema 保存格式规则,不负责理解用户的话,也不会自动把上游字段改名。
自然语言如何变成输入参数
假设用户说:“汇总这张表,商品净销售额显示前 5 名,日期明细每页 20 条。”
WorkBuddy 可以结合技能说明,把这次要求组织成下面这样的 JSON。路径是示例,需要换成任务中实际可访问的位置:
{ "file_path": "D:/reports/sales.xlsx", "output_dir": "D:/reports/output", "top_n": 5, "trend_page_size": 20}这里的 top_n 是报告排名展示数量,不是任意排序功能的开关。这套程序按净销售额排名;如果用户要求一种尚未实现的排名口径,不能只改个参数名字就声称支持。
工作流如何准备同样的参数
固定工作流通常已经有结构化数据。例如,上游返回 uploadedFile.path 和 limit,调用方可以直接写映射:
const inputs = { file_path: upstream.uploadedFile.path, top_n: upstream.limit, output_dir: "D:/reports/output"};
const result = await runSalesReport(inputs, ctx);这段代码放在调用方的异步函数中,并事先导入 runSalesReport。其中 limit 必须已经是有效整数;如果上游提供字符串,需要调用方明确转换并检查取值。
此时字段对应关系已经确定,不需要大模型参与。当前 workflow_adapter.mjs 会序列化收到的 inputs,启动 Python 子进程,再读取 JSON 结果。它不会自动推断 uploadedFile.path 应该改名为 file_path。
Excel 表头如何对应标准字段
输入对象准备好以后,还有表格内部的列名映射。对于本文的小表,可以显式传入:
{ "field_map": { "product": "宝贝标题", "amount": "本单实收", "quantity": "售出件数", "refund_status": "售后标记", "refund_amount": "实际退回金额", "refund_quantity": "实际退回件数" }}这是输入对象中的一个片段,单独传它还不能运行,需要同时提供 file_path 或 records。
映射的方向是 程序标准字段 → 原始表头名称。例如 amount: "本单实收" 表示读取“本单实收”这一列作为金额,不会修改 Excel 里的表头。
三个层次可以放在一起看:
| 层次 | 示例 | 由谁完成 |
|---|---|---|
| 用户意图变成配置 | “前 5 名” → top_n: 5 | 模型理解任务,或用户直接指定 |
| 上游字段变成接口参数 | uploadedFile.path → file_path | 调用方代码或工作流变量绑定 |
| 原始列名对应标准字段 | “宝贝标题” → product | 内置别名匹配,或显式 field_map |
所以,模型可以帮助准备映射,但最终传给脚本的映射仍然是一份可检查的结构化参数。
5. 改了表头,什么情况下还能运行
程序中的 ALIASES 维护了一组常见名称,_mapping() 据此匹配列。例如“商品”“商品名称”“产品名称”“品名”都可以对应 product。
匹配前会做名称规范化,包括处理空白、大小写和部分字符形式。这能容忍一些格式差异,但没有语义理解能力:“宝贝标题”和“商品名称”在业务上接近,程序不会因此自动认为它们相同。
当前匹配顺序是:
是否为这个字段提供了 field_map? 有 → 按指定原始列名查找,并检查该列是否存在 无 → 尝试内置别名匹配 找到多个候选 → 返回歧义错误,要求明确映射 没有找到 → 该标准字段暂时没有对应列未找到列以后,影响取决于字段用途。缺少数量列不一定妨碍金额统计;缺少金额映射则无法得到有效销售汇总,后续行处理会记录金额缺失或无效等异常。返回结果没有崩溃,并不等于业务数据已经被正确识别。
如果只是把“商品名称”改成“宝贝标题”,提供正确的 field_map 就能继续处理,通常不用修改代码。模型也可以在查看表格后帮助生成这份映射,但应检查它是否真的写进了本次输入。
如果新增的是“成本”或“库存”,情况不同。这套程序没有相应的利润或库存分析逻辑,仅增加一个表头映射无法获得新功能,还需要定义业务规则、计算方式和输出字段。
6. 用完整参数跑通退款示例
这套接口支持两种数据来源:file_path 让程序读取文件,records 直接接收已经解析好的明细数组。两者只能选一个。
为了看清参数如何起作用,下面把第一节的小表直接写成 records。在技能目录中将它保存为 request.json:
{ "records": [ {"宝贝标题": "保温杯", "本单实收": 200, "售出件数": 5, "售后标记": "未退款", "实际退回金额": 0, "实际退回件数": 0}, {"宝贝标题": "咖啡豆", "本单实收": 300, "售出件数": 3, "售后标记": "未退款", "实际退回金额": 0, "实际退回件数": 0}, {"宝贝标题": "保温杯", "本单实收": 120, "售出件数": 3, "售后标记": "部分退款", "实际退回金额": 60, "实际退回件数": 1} ], "field_map": { "product": "宝贝标题", "amount": "本单实收", "quantity": "售出件数", "refund_status": "售后标记", "refund_amount": "实际退回金额", "refund_quantity": "实际退回件数" }, "refund_row_mode": "order", "top_n": 5, "output_dir": "./output"}在这套技能源码和 Python 依赖已经准备好的前提下,从技能目录运行:
python scripts/sales_report.py --input-json request.json这里的命令依赖本文介绍的本地项目文件,不是安装 Python 后就自带的命令。相对路径以进程当前工作目录为准,实际接入时可以改用绝对路径。
程序中的 run() 按下面的顺序执行:
对应的核心方法是 _validate()、_load()、_mapping()、_components()、_aggregate() 和 _artifacts()。其中 _aggregate() 的分组累加可以类比 SQL 中的 GROUP BY + SUM,只是它还处理了无效数据、退款和数据覆盖情况。
正常返回后,读取 result.summary,应该得到以下关键字段。下面是结果节选,实际对象还包含行数、商品数等信息:
{ "gross_sales": 620, "refund_amount": 60, "net_sales": 560, "net_quantity": 10}refund_row_mode: "order" 表示原销售明细模式,计入销售额后减去退款额。另一种 transaction 模式用于独立退款流水,退款行只贡献扣减金额。两者不能仅凭“金额是不是负数”来决定。
还要注意退款与退货的区别。原销售明细只标记“已退款”,不能据此确定退回了几件商品。程序需要实际退货数量;如果只是退款、不退货,应明确填 0。数量未知时保留未知状态,不能从金额比例猜出件数。
7. 参数合法,和数据能用,需要分别检查
schemas/input.schema.json 声明 top_n 是 1 到 100 之间的整数。因此 5 和字符串 "5" 在这里不是同一种合法输入。
当前实现的运行时校验由 Python 的 _validate() 手写完成,并没有在每次运行时加载 Schema 文件,自动执行通用 JSON Schema 校验。默认值也由 Python 补充;只修改 Schema 中的 default,不会让程序的默认行为随之改变。
这意味着维护参数时,需要同时检查 Schema、校验代码和相关测试是否一致。声明了一个字段,并不等于计算程序已经使用它。
另一方面,明细单元格采用不同的处理策略。例如金额字符串 "1,200.50" 可以按数字规则清洗,"待确认" 无法解析时则记录异常。不能因为明细允许文本数字,就推断所有配置参数都允许自动转换。
| 情况 | 当前处理原则 |
|---|---|
top_n 类型错误,或同时传 file_path 与 records | 返回友好的参数错误 |
空的 records 数组 | 返回 ok=true、status=empty 和空明细 |
| 某行金额缺失或无法解析 | 排除该行,并记录到 issues |
| 某行数量无效,但金额有效 | 保留金额;数量不完整时披露覆盖情况 |
| 部分退款缺少实际退款金额 | 排除并提示,不能默认当成全额退款 |
| 多个金额候选列 | 要求明确 field_map,避免任意选列 |
这些规则有两个目的:输入错误时让调用方知道怎么修正,数据有问题时让报告读者知道哪些结果受到了影响。
8. 上下游拿到什么,日志又保存在哪里
返回值中,summary 保存总体指标,products、categories 和 daily 保存分组结果,issues 保存异常记录,business_insights 保存有证据和适用范围的业务提示。
指定 output_dir 后,程序会生成 HTML、Markdown、JSON 和 CSV 等产物。下游应读取 artifacts 中实际返回的路径,不要猜测本次报告子目录的名字。
接入时先判断状态,再读取业务数据。例如,下面是调用方函数内部的处理片段:
const result = await runSalesReport(inputs, ctx);
if (!result.ok) { return { ok: false, error: result.error, logFile: result.artifacts.log_file ?? null };}
return { ok: true, status: result.status, total: result.summary.net_sales, products: result.products, report: result.artifacts.report_html ?? null, logFile: result.artifacts.log_file ?? null};保留 status 是为了区分有数据的成功与空数据返回。只看到 ok=true 就写“本期业绩为零”,可能会掩盖没有可用明细的事实。
ctx.log 也有类似的边界。这里的 ctx 是调用方传入的对象,可以提供 log(message) 方法;它不是这套代码证明 WorkBuddy 原生支持的接口。普通使用方式可以直接调用 Python,不必经过 Node 适配器。
调用 ctx.log() 只代表向日志接收器发送消息,持久化由 run_log.py 和 run_log.mjs 实现。默认目录是 output_dir/logs,未提供 output_dir 时使用当前工作目录的 output/logs,也可以用 log_dir 单独指定。
每次运行创建独立的 UTF-8 日志,记录步骤、映射、统计情况和异常。成功或失败都应查看 artifacts.log_file;如果写入失败,会通过 LOG_WRITE_FAILED 披露,不能把它描述为日志完整保存。WorkBuddy 聊天里的说明文字不属于这份程序日志。
HTML 中的日期分页和图表切换由内嵌 JavaScript 完成。这一版的日期筛选只改变日期趋势视图,总览和商品汇总仍保持生成时的范围;JSON 和 CSV 保留完整结果。界面能筛选,不代表所有统计都会重新计算。
9. 怎样验证“AI 理解了表格”
只看 WorkBuddy 回复“已识别字段”还不够。更有用的是检查本次参数、映射日志和结果是否对应得上。
可以先运行本文的三行样例,确认总额为 620 元、退款为 60 元、净额为 560 元。再把“宝贝标题”换成另一个自定义名称:更新映射后,统计结果应该保持一致;使用仍然指向旧列名的映射时,应当明确报错。
还可以增加一列不同含义的金额,检查 WorkBuddy 是否根据已知业务口径选择,而不是看见“金额”两个字就任意取值。退款状态也应加入未退款、部分退款和申请中等情况,确认不会把申请当作退款完成。
这组验证分成两层:程序测试检查同样的参数是否得到正确结果;宿主中的实际执行检查 WorkBuddy 是否读到了正确的文件、准备了正确参数,并在有歧义时进行确认。Python 测试通过,不能代替后一层验证。
对这套技能来说,最值得维护的接口是那份传给脚本的 JSON。它把自然语言理解转成了可检查的配置,也让错误可以定位:是选错了表头、填错了参数,还是退款和汇总逻辑有问题。遇到新表格时,先检查这一层,通常比直接修改计算代码更容易找到原因。
If this article helped you, please share it with others!
Some information may be outdated






