Files
agent/skills/sheet/SKILL.md
T
2026-09-29 17:09:01 +08:00

8.9 KiB
Raw Blame History

name, description, required
name description required
sheet 表格文件(xls/xlsx/csv/ods)的读取与安全修改。自带原文校验、全簿逐格自检、公式引用调整与自动重算。不用于新建工作簿,不用于生成图表 true

sheet

调用形式(重要)

本技能通过 skill 工具执行,完整调用是:

{"op": "run", "name": "sheet", "input_args": {"action": "inspect", "file": "预算表.xlsx"}}

外层 op(固定为 run)属于 skill 工具;下文所有 JSON 示例都是 input_args 的内容,其动作键是 action,不要与外层 op 混淆。

何时使用

  • 修改表格文件中的单元格值或公式
  • 插入、删除行或列
  • 按内容定位目标行/列

支持格式:.xls、.xlsx、.csv、.ods。

不适用:新建工作簿、生成图表、执行宏。

工作流程

  1. action=inspect 查看表结构与公式(注意采用返回里的 suggested_header_row;若 multi_level_header 非 null,列名模式不可用,直接走 cells 地址模式)
  2. 按需求选择 action=apply / insert_rows / delete_rows / insert_cols / delete_cols

inspect

读取表结构、单元格值、公式。

{"action": "inspect", "file": "预算表.xlsx"}

参数:

  • file(必填):相对任务目录的路径
  • sheet(可选):只查指定 sheet
  • limit(可选):每个 sheet 预览行数,默认 50
  • header_row(可选):表头行号,默认 1

返回示例:

{
  "ok": true,
  "sheets": [
    {
      "name": "明细",
      "rows": 10,
      "cols": 7,
      "header_row": 1,
      "suggested_header_row": 1,
      "multi_level_header": null,
      "headers": ["序号", "项目", "单位", "数量", "单价", "金额", "备注"],
      "preview": [
        [1, "管道", "米", 100, 18, {"formula": "=D3*E3"}, ""],
        [2, "顶管", "米", 50, 157, {"formula": "=D4*E4"}, ""]
      ],
      "formulas": [
        {"cell": "F3", "formula": "=D3*E3"},
        {"cell": "F4", "formula": "=D4*E4"}
      ],
      "truncated": false
    }
  ]
}

要点:

  • headers 是表头行;合并单元格只有首个有值,其余为 null
  • suggested_header_row 是自动检测的表头行(中文表格常见「第 1 行合并标题 + 第 2 行真表头」);与你的 header_row 不一致时直接采用它继续后续调用,不用自己推断
  • multi_level_header 非 null(如 {"group_row": 2, "column_row": 3})= 多级表头(分组行 + 重复子列名行):列名定位必死,改用 cells 地址模式,别反复换 header_row 重试
  • 公式以 {"formula": "=..."} 表示
  • preview 可能被 limit 截断;formulas 最多列 500 条(超出时 formulas_truncated: true)
  • merged 是合并区域列表(如 ["A1:G1"])
  • truncated 为 true 时预览被截断,改动仍可命中整张表

apply(改值/改公式)

{
  "action": "apply",
  "file": "预算表.xlsx",
  "changes": [
    {
      "sheet": "明细",
      "match": {"项目": "顶管"},
      "set": {"单价": {"old": 157, "new": 180}}
    }
  ]
}

参数:

  • file(必填)
  • changes(必填):改动清单;每项可用 match+set(列名定位)或 cells(地址定位),二选一
  • header_row(可选,默认 1);各 change 可单独带 header_row 字段覆盖(多 sheet 表头位置不同时用)
  • output(可选):输出文件名(放原文件同目录;平台预处理成会话目录下的绝对路径也接受),默认原文件名加「(已改)」

cells 地址定位(多级表头 / 分组汇总表的正经出口)

{
  "action": "apply",
  "file": "预算表.xlsx",
  "changes": [
    {"sheet": "总表", "cells": {
      "D4": {"old": 157, "new": 190},
      "H4": {"new": "=D4*0.9"}
    }}
  ]
}
  • 地址从 inspect 的 preview(含列坐标提示)/formulas 里数出来;允许可选 $($D$4 同 D4)
  • 每个地址的 old 同样可选(省略 = 空格断言),与 set 语义一致
  • old 校验、合并区防护、全簿逐格自检、LO 重算与列名模式完全同源,不是降级通道

定位

match 用列名 + 值定位目标行,可多列组合:

{"match": {"项目": "顶管", "单位": "米"}}

set 指定要改的列和新旧值:

{"set": {"单价": {"old": 157, "new": 180}}}

old 可省:省略 = 断言目标格当前为空再写入(填空/补列/补公式场景);改已有值必须给 old,不一致则整体报错、不做任何改动。

改公式

new 以 = 开头即为公式;old 用字符串精确匹配:

{"set": {"金额": {"old": "=D3*E3", "new": "=D3*E3*1.1"}}}

一次改多处

changes 可包含多项,跨 sheet 也可以。

insert_rows / delete_rows

insert_rows:

{
  "action": "insert_rows",
  "file": "预算表.xlsx",
  "sheet": "明细",
  "after_match": {"项目": "顶管"},
  "count": 1,
  "fill": {"序号": 3, "项目": "新增项", "单位": "米", "数量": 20, "单价": 100, "金额": "=D4*E4"}
}
  • after_match:在此行之后插入(用列名 + 值定位)
  • count:插入行数,默认 1
  • fill:可选,为新行填充值(公式按新行实际行号自己写好);以 = 开头视为公式

delete_rows:

{
  "action": "delete_rows",
  "file": "预算表.xlsx",
  "sheet": "明细",
  "match": {"项目": "顶管"},
  "count": 1
}
  • match:要删除的行
  • count:删除行数,默认 1

行插入/删除会自动调整公式引用(含其他工作表中引用本表的跨表公式,同 Excel);合并单元格同步移动,区域内插行会自动扩大区域。

insert_cols / delete_cols

insert_cols:

{
  "action": "insert_cols",
  "file": "预算表.xlsx",
  "sheet": "明细",
  "after": "单价",
  "count": 1,
  "fill_header": "折扣"
}
  • after:在此列之后插入(用列名定位)
  • fill_header:可选,新列的表头

delete_cols:

{
  "action": "delete_cols",
  "file": "预算表.xlsx",
  "sheet": "明细",
  "col": "备注",
  "count": 1
}

列插入/删除同样会自动调整公式引用。

硬约束

  • 只改清单里指定的位置
  • 改动前校验 old(set)或 match 唯一性
  • 改动后自检:目标改动生效、其他内容未变(含公式原文)、文件可打开
  • 任一项失败 → 产物自动删除、不交付
  • 遇不支持的引用形态(数组公式、外部簿引用、结构化引用)直接报错,绝不半改交付
  • 超出能力的表(多级表头等)用 cells 地址模式处理;禁止绕开本技能用 terminal/脚本手改交付物——手改没有 old 校验、逐格自检、跨表引用检查与重算门禁,错了没人兜底

边界

  • 公式调整范围:目标表内引用、他表→目标表的跨表引用都会改;目标表→他表的引用不动(同 Excel)。 被删区域端点的区间按 Excel 语义收缩;命名范围(Tax2023 之类)不改写,引用它们的结果可能错位,需人工核对。
  • 删除跨越合并区域边界的行/列会被拒绝(行为无法推断),改为整块删或先拆合并。
  • 产物交付前已自动重算:LibreOffice 对 xlsx/xls/ods 求值并把结果写入公式缓存,可直接进预览/转 PDF/脚本读取; 重算失败时自动回退交付「未重算版」并在结果 recalc 字段标注 failed:...(未重算版仍带「打开时全量重算」标记, Excel/WPS 打开结果一样正确);结果里看到 recalc=failed 时简短告知用户一句即可,不要重试。
  • CSV 单元格一律按文本保留(「007」「1.10」不会变成 7/1.1);数字与数字文本在定位比较时互认。
  • 多级表头(分组行 + 重复子列名,如「新建顶管|数量·单价」):match/set 列名定位不支持(子列名不唯一,任何 header_row 都无解);inspect 会标 multi_level_header,请用 cells 地址模式 + 从 preview 确认坐标。更深层级(≥3 行表头)同样走 cells。

常见错误

  1. match 不唯一:多行满足条件,补充更多列条件
  2. old 不匹配:定位错了或数据已变,重新 inspect
  3. 表头不在第 1 行(标题行+表头行结构极常见):看 inspect 的 suggested_header_row;apply/insert/delete 若把标题行误当表头,报错信息里会直接给出建议行号,按其重试即可
  4. 列名不存在:报错会列出可用列名
  5. sheet 不存在:报错会列出可用 sheet 名
  6. 写入合并区域非锚点格:报错提示改用区域左上角锚点
  7. 报「不支持数组公式/外部簿引用」:该表需人工处理,不要反复重试
  8. 报「重复列名 / 检测到多级表头」:换 header_row 重试没有用(子列名天然不唯一),改用 cells 地址模式;也不要因此绕开技能去手改文件