Skip to main contentexcel-editing
**生成、编辑、修改、套公式、加图表或导出 .xlsx Excel 工作簿 / 财务模型 / 报表 / 数据表 / 预算 / 名册 / 排期** 时使用。既覆盖从零建表（表头样式·列宽·合并单元格），也覆盖：按公式建模（同比·毛利率·三年滚动预测等活公式，而非写死数值）、批量改单元格、加 sheet、插入原生图表、给已有工作簿加列或加汇总行。把 Excel/工作簿转成 PDF 也走本技能（.xlsx 为主产物）。仅当用户要 .xlsx 产物、或改/转既有 Excel 时触发；查数据库、读表格做总结、写 SQL、把数据画成图片、出纯文字数据分析报告、翻译表格内容 时不要触发。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/ZJU-REAL/HugAgentOS --skill excel-editing명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
| name | excel-editing |
| display_name | Excel 表格作业手册 |
| description | **生成、编辑、修改、套公式、加图表或导出 .xlsx Excel 工作簿 / 财务模型 / 报表 / 数据表 / 预算 / 名册 / 排期** 时使用。既覆盖从零建表（表头样式·列宽·合并单元格），也覆盖：按公式建模（同比·毛利率·三年滚动预测等活公式，而非写死数值）、批量改单元格、加 sheet、插入原生图表、给已有工作簿加列或加汇总行。把 Excel/工作簿转成 PDF 也走本技能（.xlsx 为主产物）。仅当用户要 .xlsx 产物、或改/转既有 Excel 时触发；查数据库、读表格做总结、写 SQL、把数据画成图片、出纯文字数据分析报告、翻译表格内容 时不要触发。 |
| tags | xlsx, excel, office, spreadsheet, cli |
Excel 表格作业手册
本 skill 是处理 .xlsx 文件的唯一权威入口。所有 Excel 能力都收敛成单一 CLI——excel-cli——的 5 个子命令。
目标只有一个：每次操作 .xlsx 都选对子命令、写对参数。
进入本技能前先停一秒：别走偏
只有在用户明确需要 Excel / xlsx / .xlsx / 工作簿 / spreadsheet 文件产物，
或要求生成、编辑、加 sheet、改单元格、建模型、导出 PDF 时，才进入这份 SKILL。
用户只是说"查一下数据"、"看看这个表"、"统计一下指标"时，除非同时明确要求交付
Excel/.xlsx 成稿，否则应改用 query_database、retrieve_dataset_content 或
其它更匹配的工具。
一旦确认这是 Excel 产物任务，你的最终产物必须是 .xlsx：用 excel-cli create 或
excel-cli edit 产出，并 pin_to_workspace 交付。下面几件事看上去能"完成任务"，
实际是失败：
Write 写 CSV 不可替代 excel-cli create。用户要 .xlsx 时不能写一个
.csv 兜底。csv 不带表头样式、不带列宽、不带公式——输出格式不符合用户请求
就是失败。看到用户消息里明确要 Excel/.xlsx 文件——心里默念一句"产物必须是
.xlsx"，再开始动手。- 不要把 markdown 表格塞回 chat 让用户"自己复制粘贴到 Excel"。这是 hard
fail。如果你已经写好了表格内容，用 把它生成成 .xlsx，再 +
交付。从来不是"贴在回答里收工"。
正确做法是
excel-cli create --mode workbook --sheets '[{...}]'
sandbox_get_artifact
pin_to_workspace
不要拿 list_myspace_files 返回的旧 artifact 当作"新生成的工作簿"再 pin 一遍。
sandbox_put_artifact 是把"用户这一轮上传的原始 xlsx"送进沙盒；它不是
artifact 复制器、不是"我把以前生成过的同名文件再用一次"的捷径。新工作簿永远走
excel-cli create 从零生成。pdf-cli create / word-cli create 不能替代。用户要 .xlsx 时不能直接出
.pdf 或 .docx 兜底。同时要 .xlsx + .pdf 时，.xlsx 是主产物，.pdf 是由
excel-cli convert --to pdf 从 xlsx 转出来的副产物，不能跳过 .xlsx 直接出
.pdf。改完中间稿（--patches JSON / --sheets JSON / 数据 spec）就停手，忘了
重新跑 excel-cli 出最终 .xlsx。常见现场：你把 patches 列表改了一轮，回复
就说"已经把 X 列改成 Y，patches 保存在 /workspace/patches.json"——然后收尾。
这些中间 JSON 不是用户要的东西，.xlsx 才是。中间稿每改一轮都得重新跑
excel-cli create / excel-cli edit 把新版 .xlsx 产出来，再走
sandbox_get_artifact + pin_to_workspace 把最新文件推给用户。stop 在
patches/sheets JSON 上 = 这一轮没交付。excel-cli 跑完了，只在回复里说"工作簿已生成，路径 /workspace/xxx.xlsx"
就收尾。沙盒磁盘对用户完全是黑盒——你告诉他"沙盒里有个文件在这里"，
等同于没交付：用户的对话区 / 我的空间不会自动出现这个文件，他没办法点开、
下载、看里面的数据。CLI 跑完后必须接 sandbox_get_artifact 拿 file_id，
再 pin_to_workspace 钉到工作区，用户那边才会看到 .xlsx 卡片。什么时候应该离开这份 SKILL：用户明确说要 Word / 报告 / 公文 → 那应该走
word-editing 技能。用户要 PPT / 演示文稿 → 走 ppt-design。用户要 PDF
文档（不需要 Excel） → 走 pdf-editing 的 pdf-cli create / pdf-cli reformat。
如果不小心被 load
进了这份 SKILL 但用户其实想要别的格式，先承认走错了再换工具，不要勉强用 excel-cli。
运行模型（必须先理解这个，再谈调命令）
LLM 没有 excel_* 工具可以直接调。每次 Excel 操作是 3 步组合 + 1 步交付：
# Step 1：如果用户上传过原始 xlsx（有 file_id），把它送进沙盒
sandbox_put_artifact(artifact_id="<原始 xlsx 的 file_id>",
dest_path="/workspace/in.xlsx")
→ {"ok": true, "artifact_id": "...", "dest_path": "/workspace/in.xlsx"}
# 注意：`put` = put INTO sandbox（沙盒是终点）。从零创建的场景跳过这一步。
# Step 2：bash 跑 excel-cli
bash("excel-cli <subcmd> --input /workspace/in.xlsx \
--output /workspace/out.xlsx \
<子命令特定参数>")
→ stdout 返回 JSON 结果（{"ok": bool, "meta": ...}）
# Step 3：把沙盒里的成稿提取出来登记成 artifact
sandbox_get_artifact(src_path="/workspace/out.xlsx",
name="数据汇总.xlsx")
→ {"ok": true, "file_id": "<新 file_id>", "url": "/files/...", ...}
# 注意：`get` = get OUT of sandbox（沙盒是源）。这一步返回新的 file_id。
# Step 4（必做）：交付给用户
pin_to_workspace(file_ids=["<新 file_id>"])
→ 文件出现在对话区/我的空间。没 pin = 用户看不到。
读取类子命令（read 的 summary/sheet/validate 模式）只有第 1、2 步，没有第 3、4
步（没有新文件交付）。
调用方式：只敲 excel-cli，别去 python 跑 scripts/ 里的文件
excel-cli 已经装在沙盒 PATH 上（/usr/local/bin/excel-cli），当成普通命令直接敲：
bash("excel-cli create --mode workbook --output /workspace/out.xlsx --sheets-file /workspace/data.json")
scripts/ 目录下的 _common.py / cli.py / create.py 等是实现细节，不是入口。
绝不要用 python scripts/xxx.py 去跑它们：
- ❌
python scripts/_common.py excel-cli create … —— _common.py 是共享库，
跑它什么都不会发生：它只是定义函数然后退出，不解析参数、不产文件。
（已加保护：现在会报 NotAnEntryPoint 并回显应该执行的正确命令。）
- ❌
python scripts/create.py … —— 绕过了 PATH 解析和 Python 解释器挑选逻辑，
容易撞 ModuleNotFoundError。
- ✅
excel-cli create … —— 唯一正确入口。
只有当 excel-cli 真的 command not found / 退出码 127 时，才退到
python /workspace/skills/excel-editing/scripts/cli.py <subcmd> …（用 cli.py，
不是 _common.py）。
自检：每次创建/编辑后，下一步 sandbox_get_artifact 之前，务必确认 stdout 是
{"ok": true, ...}。命令"成功了但没产出文件"——比如 stdout 为空、exit 0 但
{"ok": ...} 缺失——一律当失败处理，先查调用方式对不对，不要原样重试。
5 个子命令速查（详见 references/cli-commands.md）
| 子命令 | 用途 | 典型场景 |
|---|
excel-cli read --mode summary | 工作簿概览（sheet 名/维度/表头/样例行） | 用户上传 xlsx 后的"第一眼" |
excel-cli read --mode sheet | 单 sheet 的单元格值（可指定 range） | 提取某 sheet 数据做后续分析 |
excel-cli read --mode validate | 公式静态校验（#REF! / 跨表引用） | 用户问"这工作簿公式有没有错" |
excel-cli create --mode workbook | 数据表新建（headers + rows + 列宽） | 把表格数据落成 .xlsx |
excel-cli create --mode model | 财务/分析模型（公式 + 角色样式） | 多 sheet 含公式的成熟模型 |
excel-cli edit --patches | 批量编辑（字节保留：保 VBA/数据透视/格式） | 改公式、插行、加列、改 sheet 名 |
excel-cli edit --set-cells | 单元格写入（openpyxl 回填，可能丢宏） | 单点改值/公式，宿主无 VBA |
excel-cli edit --add-sheet | 追加新 sheet | 加 Q4 sheet、参数表 |
excel-cli edit --add-chart | 插入原生图表（bar/line/pie） | 在数据 sheet 旁加柱状图 |
excel-cli save | 另存到最终文件名 | 命名好交付名（"年度报表.xlsx"） |
excel-cli convert --to pdf | xlsx → pdf（LibreOffice） | 需要 PDF 副本时 |
优先级铁律：编辑既有 .xlsx 优先用 --patches（字节保留，不会污染 VBA/数据
透视/条件格式）；非要改的内容 --patches 表达不了，再退到 --set-cells。
永远不要把 markdown/CSV 字符串塞给模型让它"自己想象成 Excel"。
渐进式加载：什么时候去看哪份 reference
- 第一次写
excel-cli edit --patches → 必读 references/apply-edits-ops.md，
里面是 7 个 patch op（set_cell / fix_formula / replace_text / insert_row /
add_column / rename_sheet / delete_row）的卡片，每个含必填+可选 kwargs 与正反例。
- 没把握选哪个子命令 → 看
references/cli-commands.md，所有子命令的完整
argparse 参数 + 返回结构都在这里。
- 要查一份完整配方（如"用户传 xlsx → 我要插一列计算列 → 导出 PDF"）→ 看
references/workflows.md，6~8 个端到端例子。
- 报错 / 行为反直觉 → 看
references/pitfalls.md，含 4 个 edit 引擎
（--patches / --set-cells / --add-sheet / --add-chart）不能互相组合、
--set-cells 会丢 VBA 等高频踩坑。
大 payload 兜底（永远记得）
excel-cli edit --patches '[...]' / excel-cli create --sheets '[...]' 的
JSON 数组很容易很大（一个 100 行的财务模型 spec 轻松破 20KB）。bash 命令行
有 ~128KB 的 Argument list too long 上限，触发就直接报错。
永远的兜底：先 Write 把 JSON 写到 /workspace/<name>.json，再用 -file
变体：
Write(file_path="/workspace/patches.json", content="[{...}, {...}]")
bash("excel-cli edit --input /workspace/in.xlsx \\
--output /workspace/out.xlsx \\
--patches-file /workspace/patches.json")
create --sheets-file / create --spec-file / edit --set-cells-file /
edit --add-sheet-file / edit --add-chart-file 都有对应的 -file 变体。
一句话自检（交付前）
每次回复用户之前，按这个列表 5 秒过一遍。任何一项没满足 = 这一轮没交付，
回去补，不要发：
- 用户要的是 .xlsx，我交付的也是 .xlsx 吗？（不是偷偷换成了 .csv /
.pdf / .docx / 「贴在回答里的 markdown 表格让用户自己复制粘贴」？）
- 是不是用
excel-cli create（从零）或 excel-cli edit（改既有）真的产出过
/workspace/<...>.xlsx 这个文件？（没跑过这条命令 = 没有 .xlsx，必返工）
- 中途如果改过 patches / sheets / data spec 这类中间稿，改完之后有没有再跑
一次
excel-cli 把最新版 .xlsx 重新生成出来？（停在改完 patches/JSON =
没交付）
sandbox_get_artifact(src_path="/workspace/<...>.xlsx", name="...") 跑了，
拿到了 file_id 了吗？pin_to_workspace(file_ids=["<file_id>"]) 调了吗？
—— 这一步不可省：没 pin，文件只是后端 artifact 存储里的一条匿名记录，
用户在对话区 / 我的空间里完全看不到，等于这一轮任务从没存在。- 用户同时要 .xlsx + .pdf 时：两个 file_id 都进同一次
pin_to_workspace(file_ids=[...]) 调用了吗？（一次 pin 多个，别多次 pin）
- 用户指定了"放到我的空间里 XX 文件夹"：
name= 参数填了贴切的中文文件名
吗？（不是 out.xlsx / draft.xlsx 这种）
一句话回顾
看见 Excel/.xlsx 任务 → 进沙盒 → 选对 excel-cli <subcmd> → 出文件 → pin。
编辑既有工作簿优先 --patches（字节保留）；新建优先 create --mode workbook
或 --mode model；要 PDF 副本最后一步 convert --to pdf。
