dsh-excel-chat 使用指南

在 DeepSeek Harness 里用自然语言操作 Excel：读、写、算、画、改，最后自动体检 公式有没有被弄坏。

1. 安装

前提：已安装 DeepSeek Harness（dsh CLI 或桌面端）。

# 从 npm 安装（推荐）
dsh plugin --profile demo add dsh-excel-chat

# 或从 GitHub 安装
# dsh plugin --profile demo add github:hccccc01333/dsh-excel-chat

# 打开对话界面
dsh web --profile demo

锁定版本：dsh plugin --profile demo add dsh-excel-chat@0.23.1（不写版本默认 latest）。

装完先自检一次（检查宿主包隔离 + 引擎冒烟，装坏了一跑就知道）：

dsh-excel-chat-doctor
# 或：~/.dsh/profiles/demo/node_modules/.bin/dsh-excel-chat-doctor
# 对话里也可以直接发 /excel-doctor

2. 一分钟开始

打开对话后，直接说：

• “帮我把 report.xlsx 做成报表：D 列毛利、E 列合计、表头加粗、冻结首行、加筛选”
• “检查 sales.xlsx 的 D 列公式有没有错，不对的修掉”
• “按区域生成透视表，金额合计，再生成柱状图”
• “用模板给每笔订单生成发货通知”

agent 会自动调用工具完成，并把结果文件路径告诉你。

3. 工具总览

工具	作用
excel_read	精确读取：值/公式/类型/数字格式/字体/填充/对齐/合并/数据有效性
excel_profile	大表速览：表头、每列类型/缺失/唯一值/数值区间/高频值/样例 + 建议读取范围；配合 maxRows 分页读大表
excel_semantic_profile	语义画像：列角色（时间/维度/指标/标识）、数据粒度、派生指标、跨表关联键；分析类任务先跑它，避免找错列
excel_menu	不会描述也没关系：给文件就出菜单——一句话摘要 + 清洗/报表/透视/图表/体检/通知/岗位模板等可选方案，每个带示例话术，直接选
excel_insight	数据洞察：一句话摘要 + 缺失/重复/异常值/负值/空格等体检 + 下一步建议
excel_preview	表格预览：Markdown 表格（对话内展示）+ HTML 预览文件
excel_task	多步编排（steps 模式，逐步体检/修复）+ Agent 闭环（goal 模式：LLM 规划→执行→验证→重规划）
excel_explain_formula	公式白话解释：函数、引用区域、跨表引用、运算
excel_validate_formulas	静默公式错误检测：列 pattern、结构不匹配、硬编码、空行、循环引用、#REF! 等错误值
excel_compile_formula	语义 Formula IR（binary/ratio/aggregate/function）→ 确定性公式
excel_repair_formulas	确定性修复 + 可选 LLM 修复，输出修复副本并复验
excel_autofix	一键自愈：体检 → 确定性修复（可选 LLM）→ 复检 → 人话汇报；修复副本自动附带隐藏健康报告表
excel_health_report	把公式体检报告写进工作簿本身（隐藏「_dsh_体检报告」表：健康分 + 异常清单），报告跟着文件走
excel_operate	30+ 种精细化操作：写值、填充/序列、行列增删、复制/移动、排序、分类汇总、动态透视报表、高级筛选、样式（字号/边框）、数据有效性、条件格式（数据条/色阶/图标集）、自动筛选、结构化表格、页面设置、命名区域、冻结窗格、查找替换、工作表保护、邮件合并、工作表管理、合并、数据清洗（去重/填缺失/删空行空列/去空格/大小写/全角半角/分列）、整行条件高亮、两表模糊匹配；自动写审计日志
excel_undo	按审计日志回滚一次 excel_operate 编辑
excel_diff_workbook	两个 workbook 的单元格级差异
excel_validate_charts	图表结构校验
excel_create_chart / excel_modify_chart	创建/修改图表（类型/标题/图例/坐标轴），Windows + Excel
excel_create_pivot	原生数据透视表（多行/列字段、筛选器 + 值字段），Windows + Excel
excel_export_charts	导出图表 PNG，Windows + Excel

4. 典型场景

报表搭建

帮我把 report.xlsx 做成报表：D 列毛利（收入-成本）、E 列合计、表头加粗填浅灰、 冻结第一行、加筛选。

agent 会用一次 excel_operate 完成 set + style + freezePanes + autoFilter，并返回 操作后公式复验结果。

公式体检与修复

检查 sales.xlsx 的 D 列公式是否都是“收入-成本”，不对的修掉，输出到 repaired.xlsx。

流程：excel_read 看清现状 → excel_validate_formulas 定位异常 → excel_repair_formulas 修复并复验。

大表速览与一键自愈

先看一下 D:\data\销售台账.xlsx 的结构，再按页读数据。

流程：excel_profile 返回紧凑画像（每个表/每列的类型、缺失、唯一值、数值 区间、高频值、样例与建议读取范围）；大表按 readHint 起手、用 excel_read 的 maxRows 分页读取，避免一次灌入整张表。

刚才那轮修改后帮我检查并修一下公式。

excel_autofix 一条命令完成“体检 → 确定性修复（可选 useLlm: true 走 LLM） → 复检 → 汇报”，输出修复副本与修复前后的异常数。

不知道怎么开口？

用户：D:\data\销售台账.xlsx，帮我看看能做啥

agent 会自动调用 excel_menu，先给你一句话说清这张表里有什么（行数、列数、 表头、空值、公式），再列出一份菜单：

1. 数据清洗——去重、补空值、去空格、分列
2. 一键经营报表——按区域分组、金额合计
3. 动态透视汇总 / 原生透视表
4. 图表——柱状图 / 折线图 / 饼图
5. 公式体检 + 自愈
6. 批量通知 / 岗位模板（运营 / 产品 / 数分）

每个选项都带一句示例话术，直接回复编号或把示例话术发过来即可；做完不满意 可以用 excel_undo 回滚。把“描述需求”变成“选需求”，不需要你会 Excel 术语。

数据清洗

把 sales.xlsx 按“产品”去重（保留第一条），B 列空值填 0，去掉名称首尾空格， 再把 SKU 列按 “-” 分成两列。

一次 excel_operate 的 operations 数组完成：dedupeRows → fillMissing（mode: value / forward / left）→ trimText → splitColumn（自动在右侧插入新列，已有列右移、公式引用联动）。 还有 removeEmptyRows / removeEmptyColumns / changeCase （upper / lower / proper）。

数据洞察、高亮与模糊匹配

帮我看看 sales.xlsx 这表有什么问题 / 把订单表和价目表按名称模糊匹配，把编码 填回 C 列 / 把“苹果”所在的行全部标黄。

excel_insight 一次给出摘要 + 缺失/重复/异常值/负值/空格等体检结论和建议； excel_operate 的 highlightRows 按条件整行高亮（默认黄色），fuzzyMatch 把两表按键相似度匹配（如对账、名称有错别字）并回填目标列，可同时输出匹配 分数。

多步任务与公式解释

先清洗 sales.xlsx（去重、补空值），再按区域汇总，一次做完 / 帮我解释一下 D 列这个公式是什么意思。

excel_task 把多个 excel_operate 步骤串成一次调用，每步结束自动体检公式、 坏了自动修复，再进入下一步（复杂任务一次完成）；excel_explain_formula 把公式翻译成人话：用了哪些函数、引用哪些区域、是否跨表。

表格预览

看看 D:\demo-sales.xlsx 这张表长什么样。

excel_preview 把表渲染成 Markdown 表格直接显示在对话里，同时在工作簿旁生成 <文件名>.preview.html，用浏览器打开就能看到完整的表格视图（公式、样式按 单元格内容展示）。

Goal 模式（Agent 闭环）

把这个表做成一张月度经营报表，金额按区域汇总、表头加粗、自动筛选。

不写步骤，直接给目标：excel_task 的 goal 模式会让 LLM 规划操作序列， 执行后由 LLM 验证器判断目标是否达成；没达成就带着上一轮结果重新规划， 最多 maxRounds 轮（默认 2）。每一步仍然经过公式体检 + 确定性修复。

数据分析（透视 / 汇总 / 高级筛选）

按区域生成动态透视报表（金额合计 + 数量计数），再给订单表做分类汇总，F 列加 数据条条件格式，最后保护工作表。

aggregateReport 生成的是实时 SUMIFS 联动报表；excel_create_pivot 生成的是 Excel 原生可交互透视表；subtotal 负责分类小计。

想要一条指令出整套经营报表，用 report 模板操作（排序 + 分类汇总 + 动态透视 汇总 + 自动筛选 + 表头样式 + 冻结首行 + 数字格式一步完成）：

用 report 给订单表按区域生成经营报表：金额合计，输出到“经营报表”，数字格式 用 #,##0.00。

跨表补列（VLOOKUP）

给订单表加一列“产品名称”，用 VLOOKUP 从产品价目表按产品代码查。

批量通知（邮件合并）

用“通知模板”表（含 {区域}、{数量} 占位符）给每笔订单生成一行通知，放到 “发货通知”表。

图表

用 excel_create_chart 给订单表建柱状图：区域为分类、金额为数值，标题“区域金额”。

Windows + Excel 环境可用；图表创建后可继续用 excel_modify_chart 改类型/标题/ 坐标轴。

5. 平台与限制

• 公式校验、修复、读写、样式、汇总、合并、邮件合并等跨平台（macOS / Linux / Windows）。
• 图表创建/改参、原生透视表、图表导出依赖 Windows + 本机安装 Microsoft Excel。
• excel_undo 是内容级撤销：单元格值/公式/样式会恢复；插入/删除的行列结构不会 消失（内容会还原）。如果文件在编辑后被再次修改，回滚会拒绝执行而不是覆盖。
• 删除行列时，引用被删单元格的公式会变成 #REF!（与 Excel 行为一致），验证器 会把它报为错误值。

6. 常见问题

模型找不到我的文件？ 告诉它文件的绝对路径（如 D:\data\销售台账.xlsx），或先 让它用 excel_read 看一下。

为什么报告里有异常但没修复？ 有些异常（如结构不匹配）需要 LLM 修复，调用 excel_repair_formulas 时加 useLlm: true；确定性修复只处理引用偏移和空行填充。

想一条命令体检 + 修复？ 用 excel_autofix：默认走确定性修复；结构不匹配 加 useLlm: true 交给 LLM。

撤销失败说前置条件不匹配？ 说明文件在操作之后又被改过，日志与现状对不上， 这是保护机制，不是 bug。

7. 反馈

问题与建议请到 https://github.com/hccccc01333/dsh-excel-chat/issues 提交。