sheet-edit 更名 sheet 并扩语义为「读+安全修改」:① 目录/frontmatter/文档全部改名(引用面零残留);description 重写为路由优先——列全格式 xls/xlsx/csv/ods、inspect 读结构与定位、apply/cells 最小改动、自带四重保障、明确「不用于新建工作簿」。命名讨论定稿:弃 excel/xlsx(名字越强,「帮我生成个excel」的误召唤越难用描述压住),sheet 中性、召回靠 description 行补足。② set/cells 的 old 改为可选:省略=断言目标格为空再写入(填空/补列/给插入行补公式的正经出口),非空拒写并报当前值;改已有值必须给 old——保障链不变,只是把「写新内容」纳入技能,杜绝 AI 为此绕道手改。③ skills.js 落地 required 机制:frontmatter required:true → prompt 列表行首标 **required**,用户在 system-prompt 模板写的「Skills marked **required** must be used」条款自此有了作用对象(sheet 首个标记);此前该条款空转。④ 重启验证:skills=data-page,img-utils,sheet,x2pdf,prompt 快照含 **required** sheet 且零 sheet-edit 残留;容器 8 项功能回归全过

This commit is contained in:
2026-09-28 11:24:42 +08:00
parent 039d8ba6dc
commit 37d8c356a0
8 changed files with 35 additions and 18 deletions
+6 -3
View File
@@ -63,14 +63,17 @@ async function listSkills(ctx) {
if (!fs.existsSync(mdPath)) continue; if (!fs.existsSync(mdPath)) continue;
let content; let content;
try { content = await fsp.readFile(mdPath, 'utf8'); } catch (_) { continue; } try { content = await fsp.readFile(mdPath, 'utf8'); } catch (_) { continue; }
out.push({ name: e.name, description: extractDescription(content) }); // frontmatter 可选 required: true —— 进 system prompt 时行首标 **required**(配合模板里的强制条款)
let required = false;
try { required = parseFrontMatter(content).required === true; } catch (_) {}
out.push({ name: e.name, description: extractDescription(content), required: required });
} }
out.sort((a, b) => a.name.localeCompare(b.name)); out.sort((a, b) => a.name.localeCompare(b.name));
return out; return out;
} }
// ---------- system prompt 注入:可用技能列表 ---------- // ---------- system prompt 注入:可用技能列表 ----------
// 把技能列表格式化成 “## Available Skills” 段落(每行 `- 名字: 描述`; // 把技能列表格式化成 “## Available Skills” 段落(每行 `- [**required** ]名字: 描述`;
// listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存; // listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存;
// 参数查 op=get,执行 op=run;描述如需实时复核仍可查 op=list)。 // 参数查 op=get,执行 op=run;描述如需实时复核仍可查 op=list)。
// 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后 // 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后
@@ -81,7 +84,7 @@ function formatSkillListForPrompt(list) {
const lines = list.map(s => { const lines = list.map(s => {
// 描述压成单行:YAML 块标量可能带换行,不能让它撞破列表结构 // 描述压成单行:YAML 块标量可能带换行,不能让它撞破列表结构
const desc = String(s.description || '').replace(/\s*\n\s*/g, ' ').trim(); const desc = String(s.description || '').replace(/\s*\n\s*/g, ' ').trim();
return '- ' + s.name + (desc ? ': ' + desc : ''); return (s.required ? '- **required** ' : '- ') + s.name + (desc ? ': ' + desc : '');
}); });
return '## Available Skills\n' + lines.join('\n'); return '## Available Skills\n' + lines.join('\n');
} }
@@ -1,16 +1,17 @@
--- ---
name: sheet-edit name: sheet
description: 结构化修改表格文件。内容定位(列名 + 值),最小改动。支持改值、改公式、插入/删除行列,公式引用自动调整。 description: 表格文件(xls/xlsx/csv/ods)的读取与安全修改。inspect 看结构/公式/表头定位;apply 按「列名+值」或 cells 地址最小改动,自带 old 校验、全簿逐格自检、公式引用调整与自动重算。不用于新建工作簿、图表生成。
required: true
--- ---
# sheet-edit # sheet
## 调用形式(重要) ## 调用形式(重要)
本技能通过 `skill` 工具执行,完整调用是: 本技能通过 `skill` 工具执行,完整调用是:
```json ```json
{"op": "run", "name": "sheet-edit", "input_args": {"action": "inspect", "file": "预算表.xlsx"}} {"op": "run", "name": "sheet", "input_args": {"action": "inspect", "file": "预算表.xlsx"}}
``` ```
外层 `op`(固定为 run)属于 skill 工具;**下文所有 JSON 示例都是 `input_args` 的内容**,其动作键是 `action`,不要与外层 `op` 混淆。 外层 `op`(固定为 run)属于 skill 工具;**下文所有 JSON 示例都是 `input_args` 的内容**,其动作键是 `action`,不要与外层 `op` 混淆。
@@ -112,13 +113,14 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最
"changes": [ "changes": [
{"sheet": "总表", "cells": { {"sheet": "总表", "cells": {
"D4": {"old": 157, "new": 190}, "D4": {"old": 157, "new": 190},
"F4": {"old": 120, "new": 150} "H4": {"new": "=D4*0.9"}
}} }}
] ]
} }
``` ```
- 地址从 inspect 的 `preview`(含列坐标提示)/`formulas` 里数出来;允许可选 `$`(`$D$4` 同 `D4`) - 地址从 inspect 的 `preview`(含列坐标提示)/`formulas` 里数出来;允许可选 `$`(`$D$4` 同 `D4`)
- 每个地址的 `old` 同样可选(省略 = 空格断言),与 `set` 语义一致
- old 校验、合并区防护、全簿逐格自检、LO 重算与列名模式**完全同源**,不是降级通道 - old 校验、合并区防护、全簿逐格自检、LO 重算与列名模式**完全同源**,不是降级通道
### 定位 ### 定位
@@ -135,7 +137,7 @@ description: 结构化修改表格文件。内容定位(列名 + 值),最
{"set": {"单价": {"old": 157, "new": 180}}} {"set": {"单价": {"old": 157, "new": 180}}}
``` ```
`old` 必须与实际值一致,否则整体报错,不做任何改动。 `old` 可省:**省略 = 断言目标格当前为空再写入**(填空/补列/补公式场景);改已有值必须给 `old`,不一致则整体报错、不做任何改动。
### 改公式 ### 改公式
@@ -1,4 +1,4 @@
"""sheet-edit 内部库。""" """sheet 内部库。"""
class UserError(Exception): class UserError(Exception):
@@ -1,4 +1,4 @@
"""sheet-edit 的各个 op 实现。""" """sheet 的各个 op 实现。"""
import datetime import datetime
import re import re
import shutil import shutil
@@ -128,11 +128,20 @@ def apply(args):
plan.extend(_resolve_change(wb, ch, header_row)) plan.extend(_resolve_change(wb, ch, header_row))
for item in plan: for item in plan:
if not locate.value_eq(item['expected_old'], item['actual_old']): # csv 往返的空串视同空格;省略 old = 空格断言,给了 old = 精确校验
act = None if item['actual_old'] == '' else item['actual_old']
exp = item['expected_old']
if exp is _MISSING:
if act is not None:
raise UserError(
f"目标格非空,拒绝无 old 写入: {item['sheet']} 第 {item['row']} 行 "
f"'{item['col_name']}' 当前为 {act!r}(填空应保证目标为空;改已有值必须提供 old)"
)
elif not locate.value_eq(exp, act):
raise UserError( raise UserError(
f"旧值不匹配: {item['sheet']} 第 {item['row']} 行 " f"旧值不匹配: {item['sheet']} 第 {item['row']} 行 "
f"'{item['col_name']}': 期望 {item['expected_old']!r}, " f"'{item['col_name']}': 期望 {exp!r}, "
f"实际 {_json_safe(item['actual_old'])!r}" f"实际 {_json_safe(act)!r}"
) )
before = _snapshot(wb) before = _snapshot(wb)
@@ -209,6 +218,9 @@ def _resolve_change(wb, ch, header_row):
_ADDR_RE = re.compile(r'^\$?([A-Za-z]{1,3})\$?(\d{1,7})$') _ADDR_RE = re.compile(r'^\$?([A-Za-z]{1,3})\$?(\d{1,7})$')
# set/cells 的 old 缺省哨兵:省略 old = 断言目标格当前为空再写入(填空);改已有值必须显式 old。
_MISSING = object()
def _resolve_cells(ws, sheet, cells_spec): def _resolve_cells(ws, sheet, cells_spec):
"""地址模式:cells = {"C5": {"old": ..., "new": ...}, ...}。多级表头等列名不可用场景的正经出口, """地址模式:cells = {"C5": {"old": ..., "new": ...}, ...}。多级表头等列名不可用场景的正经出口,
@@ -227,8 +239,8 @@ def _resolve_cells(ws, sheet, cells_spec):
def _mk_item(ws, sheet, row, col, label, spec, match_info): def _mk_item(ws, sheet, row, col, label, spec, match_info):
if not isinstance(spec, dict) or 'old' not in spec or 'new' not in spec: if not isinstance(spec, dict) or 'new' not in spec:
raise UserError(f"'{label}' 的设值必须是 {{\"old\": ..., \"new\": ...}} 格式") raise UserError(f"'{label}' 的设值必须是 {{\"new\": ..., \"old\": 可选...}} 格式")
actual = ws.cell(row, col).value actual = ws.cell(row, col).value
if isinstance(actual, ArrayFormula): if isinstance(actual, ArrayFormula):
raise UserError( raise UserError(
@@ -244,7 +256,7 @@ def _mk_item(ws, sheet, row, col, label, spec, match_info):
'col': col, 'col': col,
'col_name': label, 'col_name': label,
'match': match_info, 'match': match_info,
'expected_old': spec['old'], 'expected_old': spec['old'] if 'old' in spec else _MISSING,
'actual_old': actual, 'actual_old': actual,
'new': new, 'new': new,
} }
@@ -1,6 +1,6 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
"""sheet-edit 技能入口。接收一个 JSON 参数,按其中 action 键分发(旧键名 op 仍兼容)。""" """sheet 技能入口。接收一个 JSON 参数,按其中 action 键分发(旧键名 op 仍兼容)。"""
import json import json
import sys import sys
from pathlib import Path from pathlib import Path