From d4f83b069465b663ece61b0d95917e272bf50412 Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 28 Sep 2026 10:16:17 +0800 Subject: [PATCH] =?UTF-8?q?sheet-edit=20=E9=A6=96=E6=88=98=E5=A4=8D?= =?UTF-8?q?=E7=9B=98=E4=B8=A4=E6=94=B9=E8=BF=9B=EF=BC=9A=E2=91=A0=20?= =?UTF-8?q?=E5=86=85=E5=B1=82=E5=8A=A8=E4=BD=9C=E9=94=AE=20op=E2=86=92acti?= =?UTF-8?q?on=EF=BC=88run.py=20=E5=85=BC=E5=AE=B9=E6=97=A7=E9=94=AE=20op?= =?UTF-8?q?=20=E7=BC=BA=E7=9C=81=20inspect=EF=BC=89=EF=BC=8C=E6=B6=88?= =?UTF-8?q?=E9=99=A4=E4=B8=8E=20skill=20=E5=B7=A5=E5=85=B7=E5=A4=96?= =?UTF-8?q?=E5=B1=82=20op=3Drun=20=E7=9A=84=E6=92=9E=E5=90=8D=E2=80=94?= =?UTF-8?q?=E2=80=94AI=20=E7=85=A7=E6=8A=84=E7=A4=BA=E4=BE=8B=E6=BC=8F?= =?UTF-8?q?=E5=A4=96=E5=B1=82=E5=8F=82=E6=95=B0=E3=80=81=E6=88=96=E6=8A=8A?= =?UTF-8?q?=E5=86=85=E5=B1=82=E5=80=BC=E5=A1=AB=E8=BF=9B=E5=A4=96=E5=B1=82?= =?UTF-8?q?=E6=9E=9A=E4=B8=BE=E7=9A=84=E6=A0=B9=E5=9B=A0=EF=BC=9BSKILL.md?= =?UTF-8?q?=20=E9=A1=B6=E9=83=A8=E6=96=B0=E5=A2=9E=E3=80=8C=E8=B0=83?= =?UTF-8?q?=E7=94=A8=E5=BD=A2=E5=BC=8F=E3=80=8D=E7=AB=A0=E8=8A=82=E7=BB=99?= =?UTF-8?q?=E5=87=BA=E5=AE=8C=E6=95=B4=E5=A4=96=E5=B1=82=E8=B0=83=E7=94=A8?= =?UTF-8?q?=E5=B9=B6=E5=A3=B0=E6=98=8E=E4=B8=8B=E6=96=87=E5=9D=87=E4=B8=BA?= =?UTF-8?q?=20input=5Fargs=E3=80=82=E2=91=A1=20=E8=A1=A8=E5=A4=B4=E8=A1=8C?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E9=9D=A0=20AI=20=E8=87=AA=E8=A7=89=EF=BC=9Al?= =?UTF-8?q?ocate.detect=5Fheader=5Frow=20=E6=89=AB=E6=8F=8F=E5=89=8D=2010?= =?UTF-8?q?=20=E8=A1=8C=EF=BC=88=E5=80=99=E9=80=89=3D=E9=9D=9E=E7=A9=BA?= =?UTF-8?q?=E5=85=A8=E5=AD=97=E7=AC=A6=E4=B8=B2=E4=B8=94=E4=BA=92=E4=B8=8D?= =?UTF-8?q?=E9=87=8D=E5=A4=8D=E5=8F=96=E6=9C=80=E5=A4=9A=E5=88=97=EF=BC=89?= =?UTF-8?q?=EF=BC=8Cinspect=20=E6=AF=8F=20sheet=20=E8=BF=94=E5=9B=9E=20sug?= =?UTF-8?q?gested=5Fheader=5Frow=EF=BC=9Bbuild=5Fcol=5Fmap=20=E5=8F=AA?= =?UTF-8?q?=E8=A7=A3=E6=9E=90=E5=87=BA=201=20=E5=88=97=EF=BC=88=E5=85=B8?= =?UTF-8?q?=E5=9E=8B=EF=BC=9A=E6=A8=AA=E8=B7=A8=E5=85=A8=E8=A1=8C=E7=9A=84?= =?UTF-8?q?=E5=90=88=E5=B9=B6=E6=A0=87=E9=A2=98=E8=A2=AB=E5=BD=93=E8=A1=A8?= =?UTF-8?q?=E5=A4=B4=EF=BC=89=E4=B8=94=E6=A3=80=E6=B5=8B=E5=88=B0=E4=B8=8D?= =?UTF-8?q?=E5=90=8C=E8=A1=8C=E6=97=B6=E7=9B=B4=E6=8E=A5=E6=8A=A5=E9=94=99?= =?UTF-8?q?=E7=BB=99=E5=87=BA=20header=5Frow=3DN=20=E5=BB=BA=E8=AE=AE?= =?UTF-8?q?=E2=80=94=E2=80=94=E8=B7=B3=E8=BF=87=20inspect=20=E7=9B=B4?= =?UTF-8?q?=E6=8E=A5=20apply=20=E4=B9=9F=E8=83=BD=E4=B8=80=E6=AC=A1?= =?UTF-8?q?=E6=8A=A5=E9=94=99=E8=87=AA=E6=84=88=EF=BC=8C=E6=AD=A3=E6=98=AF?= =?UTF-8?q?=E3=80=8C=E6=A0=87=E9=A2=98=E8=A1=8C+=E8=A1=A8=E5=A4=B4?= =?UTF-8?q?=E8=A1=8C=E3=80=8D=E4=B8=AD=E6=96=87=E8=A1=A8=E6=A0=BC=E7=BF=BB?= =?UTF-8?q?=E8=BD=A6=E7=8E=B0=E5=9C=BA=E7=9A=84=E5=85=9C=E5=BA=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/sheet-edit/SKILL.md | 30 ++++++++++++++++++-------- skills/sheet-edit/lib/locate.py | 38 ++++++++++++++++++++++++++++++++- skills/sheet-edit/lib/ops.py | 1 + skills/sheet-edit/run.py | 8 +++---- 4 files changed, 63 insertions(+), 14 deletions(-) diff --git a/skills/sheet-edit/SKILL.md b/skills/sheet-edit/SKILL.md index 3c08fef..9154f23 100644 --- a/skills/sheet-edit/SKILL.md +++ b/skills/sheet-edit/SKILL.md @@ -5,6 +5,16 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 # sheet-edit +## 调用形式(重要) + +本技能通过 `skill` 工具执行,完整调用是: + +```json +{"op": "run", "name": "sheet-edit", "input_args": {"action": "inspect", "file": "预算表.xlsx"}} +``` + +外层 `op`(固定为 run)属于 skill 工具;**下文所有 JSON 示例都是 `input_args` 的内容**,其动作键是 `action`,不要与外层 `op` 混淆。 + ## 何时使用 - 修改表格文件中的单元格值或公式 @@ -17,15 +27,15 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ## 工作流程 -1. `op=inspect` 查看表结构与公式 -2. 按需求选择 `op=apply` / `op=insert_rows` / `op=delete_rows` / `op=insert_cols` / `op=delete_cols` +1. `action=inspect` 查看表结构与公式(注意采用返回里的 `suggested_header_row`) +2. 按需求选择 `action=apply` / `insert_rows` / `delete_rows` / `insert_cols` / `delete_cols` ## inspect 读取表结构、单元格值、公式。 ```json -{"op": "inspect", "file": "预算表.xlsx"} +{"action": "inspect", "file": "预算表.xlsx"} ``` 参数: @@ -45,6 +55,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 "rows": 10, "cols": 7, "header_row": 1, + "suggested_header_row": 1, "headers": ["序号", "项目", "单位", "数量", "单价", "金额", "备注"], "preview": [ [1, "管道", "米", 100, 18, {"formula": "=D3*E3"}, ""], @@ -62,6 +73,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 要点: - `headers` 是表头行;合并单元格只有首个有值,其余为 `null` +- `suggested_header_row` 是自动检测的表头行(中文表格常见「第 1 行合并标题 + 第 2 行真表头」);与你的 `header_row` 不一致时直接采用它继续后续调用,不用自己推断 - 公式以 `{"formula": "=..."}` 表示 - `preview` 可能被 `limit` 截断;`formulas` 最多列 500 条(超出时 `formulas_truncated: true`) - `merged` 是合并区域列表(如 `["A1:G1"]`) @@ -71,7 +83,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ```json { - "op": "apply", + "action": "apply", "file": "预算表.xlsx", "changes": [ { @@ -123,7 +135,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ```json { - "op": "insert_rows", + "action": "insert_rows", "file": "预算表.xlsx", "sheet": "明细", "after_match": {"项目": "顶管"}, @@ -140,7 +152,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ```json { - "op": "delete_rows", + "action": "delete_rows", "file": "预算表.xlsx", "sheet": "明细", "match": {"项目": "顶管"}, @@ -159,7 +171,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ```json { - "op": "insert_cols", + "action": "insert_cols", "file": "预算表.xlsx", "sheet": "明细", "after": "单价", @@ -175,7 +187,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 ```json { - "op": "delete_cols", + "action": "delete_cols", "file": "预算表.xlsx", "sheet": "明细", "col": "备注", @@ -207,7 +219,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最 1. **match 不唯一**:多行满足条件,补充更多列条件 2. **old 不匹配**:定位错了或数据已变,重新 inspect -3. **表头不在第 1 行**:传 `header_row` +3. **表头不在第 1 行(标题行+表头行结构极常见)**:看 inspect 的 `suggested_header_row`;apply/insert/delete 若把标题行误当表头,报错信息里会直接给出建议行号,按其重试即可 4. **列名不存在**:报错会列出可用列名 5. **sheet 不存在**:报错会列出可用 sheet 名 6. **写入合并区域非锚点格**:报错提示改用区域左上角锚点 diff --git a/skills/sheet-edit/lib/locate.py b/skills/sheet-edit/lib/locate.py index abfbd05..32a0a3a 100644 --- a/skills/sheet-edit/lib/locate.py +++ b/skills/sheet-edit/lib/locate.py @@ -6,6 +6,32 @@ def is_formula(v) -> bool: return isinstance(v, str) and v.startswith('=') +def detect_header_row(ws, scan=10, col_cap=200) -> int: + """扫描前 scan 行猜表头行(只读不写,纯建议用)。 + + 候选条件:行内非空值 ≥ 2 且全部是普通字符串(排掉单值标题行和含数字/公式的数据行),行内不重复。 + 取非空格数最多的最早候选行;找不到则回退 1。""" + best_row, best_cnt = 1, 0 + max_c = min(ws.max_column, col_cap) + for r in range(1, min(scan, ws.max_row) + 1): + vals = [] + ok = True + for c in range(1, max_c + 1): + v = ws.cell(r, c).value + if v is None or v == '': + continue + if isinstance(v, str) and not v.startswith('='): + vals.append(v.strip()) + else: + ok = False + break + if not ok or len(vals) < 2 or len(set(vals)) != len(vals): + continue + if len(vals) > best_cnt: + best_row, best_cnt = r, len(vals) + return best_row + + def value_eq(a, b) -> bool: if a is None and b is None: return True @@ -34,7 +60,17 @@ def build_col_map(ws, header_row: int) -> dict: raise UserError(f"表头行 {header_row} 存在重复列名: '{name}'") col_map[name] = c if not col_map: - raise UserError(f"表头行 {header_row} 为空,无法识别列名") + suggest = detect_header_row(ws) + extra = f";疑似真实表头在第 {suggest} 行,请传 header_row={suggest} 重试" if suggest != header_row else '' + raise UserError(f"表头行 {header_row} 为空,无法识别列名{extra}") + if len(col_map) == 1: + # 典型现场:第 1 行是横跨全行的合并标题,单值被当成唯一列名 + suggest = detect_header_row(ws) + if suggest != header_row: + raise UserError( + f"表头行 {header_row} 只解析出 1 列('{next(iter(col_map))}'),像标题行;" + f"疑似真实表头在第 {suggest} 行,请传 header_row={suggest} 重试" + ) return col_map diff --git a/skills/sheet-edit/lib/ops.py b/skills/sheet-edit/lib/ops.py index 704a131..c653a44 100644 --- a/skills/sheet-edit/lib/ops.py +++ b/skills/sheet-edit/lib/ops.py @@ -72,6 +72,7 @@ def _sheet_info(ws, name, header_row, limit): 'rows': ws.max_row, 'cols': ws.max_column, 'header_row': header_row, + 'suggested_header_row': locate.detect_header_row(ws), 'headers': [ _json_safe(ws.cell(header_row, c).value) for c in range(1, ws.max_column + 1) diff --git a/skills/sheet-edit/run.py b/skills/sheet-edit/run.py index e8e744f..3c7912b 100644 --- a/skills/sheet-edit/run.py +++ b/skills/sheet-edit/run.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- -"""sheet-edit 技能入口。接收一个 JSON 参数,分发到对应 op。""" +"""sheet-edit 技能入口。接收一个 JSON 参数,按其中 action 键分发(旧键名 op 仍兼容)。""" import json import sys from pathlib import Path @@ -33,10 +33,10 @@ def main(): _err("input_args 必须是 JSON 对象") return 1 - op = args.get('op') - handler = HANDLERS.get(op) + action = args.get('action') or args.get('op') or 'inspect' + handler = HANDLERS.get(action) if not handler: - _err(f"未知 op: {op!r}(支持: {', '.join(HANDLERS.keys())})") + _err(f"未知 action: {action!r}(支持: {', '.join(HANDLERS.keys())})") return 1 try: