sheet-edit 首战复盘两改进:① 内层动作键 op→action(run.py 兼容旧键 op 缺省 inspect),消除与 skill 工具外层 op=run 的撞名——AI 照抄示例漏外层参数、或把内层值填进外层枚举的根因;SKILL.md 顶部新增「调用形式」章节给出完整外层调用并声明下文均为 input_args。② 表头行不再靠 AI 自觉:locate.detect_header_row 扫描前 10 行(候选=非空全字符串且互不重复取最多列),inspect 每 sheet 返回 suggested_header_row;build_col_map 只解析出 1 列(典型:横跨全行的合并标题被当表头)且检测到不同行时直接报错给出 header_row=N 建议——跳过 inspect 直接 apply 也能一次报错自愈,正是「标题行+表头行」中文表格翻车现场的兜底

This commit is contained in:
2026-09-28 10:16:17 +08:00
parent efe3dcc910
commit d4f83b0694
4 changed files with 63 additions and 14 deletions
+21 -9
View File
@@ -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. **写入合并区域非锚点格**:报错提示改用区域左上角锚点
+37 -1
View File
@@ -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
+1
View File
@@ -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)
+4 -4
View File
@@ -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: