mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
4323 words
11 minutes
WorkBuddy Skill 实战:Excel 读表、字段映射与参数校验
2026-10-02

我做了一个根据销售 Excel 生成商品汇报的 Skill,逐步加上商品排名、退款处理、图表、日期分页和日志保存。功能能运行以后,一个更基础的问题反而变得重要:用户只上传了一张表,程序需要的 file_path、field_map 和退款口径,到底是谁准备的?

如果表头从“商品名称”改成“宝贝标题”,WorkBuddy 是否还能处理?既然已经有 schemas 文件夹,参数是不是会自动转换?又是哪一段代码让 WorkBuddy 先看表格?

这些问题对应不同环节。本文以我写的 product-sales-report 1.4 版为例,把一次任务从自然语言到报告文件的过程拆开说明。文中的目录和接口属于这套自定义实现,不代表 WorkBuddy 所有技能都必须采用同样的结构,也不假设它原生提供工作流节点或 ctx 接口。

1. 先用一张小表明确要算什么#

假设业务提供了下面三条销售明细,金额单位为元,数量单位为件。这是本文构造的演示数据。

宝贝标题本单实收售出件数售后标记实际退回金额实际退回件数
保温杯2005未退款00
咖啡豆3003未退款00
保温杯1203部分退款601

这里先约定一个关键前提:每行代表原销售明细,“本单实收”保存退款前的实收金额,退款额单独记录。 如果业务系统里的“本单实收”已经减过退款,下面的计算就不能直接套用。

按这个约定,预期结果是:

正向销售额 = 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() 按下面的顺序执行:

flowchart TD A[接收输入参数] --> B[校验类型并补充默认配置] B --> C[读取 Excel 或 records] C --> D[映射原始表头] D --> E[清洗数据并应用退款口径] E --> F[按商品、品类和日期汇总] F --> G[生成业务提示和报告] G --> H[返回 JSON 与产物路径]

对应的核心方法是 _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。它把自然语言理解转成了可检查的配置,也让错误可以定位:是选错了表头、填错了参数,还是退款和汇总逻辑有问题。遇到新表格时,先检查这一层,通常比直接修改计算代码更容易找到原因。

Share

If this article helped you, please share it with others!

WorkBuddy Skill 实战:Excel 读表、字段映射与参数校验
https://mizuki.mysqil.com/posts/workbuddy-sales-report-skill/
Author
梦幻晨风
Published at
2026-10-02
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents