dsh-excel-chat

dsh-excel-chat — 和 Excel 对话，把活干完

简体中文 | English

_{第三方（dsh.so）对发布版本做静态安全扫描与 安装运行验证：当前 风险 low、0 条严重/高危/中危发现、未检测到外部凭据。}

在 DeepSeek Harness 里用自然语言 操作 Excel：说一句“给 D 列加毛利公式、表头加粗、冻结首行、加筛选”，agent 会自动 调用 excel_operate 完成；每次编辑后自动体检公式有没有被弄坏，也可以让它 “检查这个表哪里算错了”并自动修复。所有工作都在对话里完成，不需要记 Excel 操作。

为什么用它

大多数“让 AI 改表格”的方案到执行就结束了——它把公式写下去，然后告诉你“已完成”。 这个项目在执行之后还有两步，那两步才是它存在的理由：

1. 它验证自己有没有改坏。 每次操作后自动体检：列内公式模式是否偏移、有没有 hardcode、引用是否失效、有没有循环引用。改坏了它会说，而不是等你打开 Excel 才发现。
2. 它给出改前改后的证据。 单元格级 diff、可回滚的审计日志、写进文件本身的健康报告。

第三件不太显眼但同样重要：核心能力不依赖 Excel。公式校验与修复、读写单元格、 样式、汇总、关联、透视表（写 XML）都是纯 JavaScript 实现的，macOS 和 Linux 上一样能跑； 只有需要真正调用 Excel 的功能（图表、原生透视表、PDF 导出）才要求 Windows。

最近更新

v0.43.0（2026-10-15）· 完整更新日志 · Releases

目录

• 为什么用它 · 最近更新
• 功能实录 · 架构 · 5 分钟上手
• 工具（先看懂文件 · 动手改文件 · 公式体检与修复 · 对比与图表）
• 评测与可靠性 · 已知限制 · 相关链接

想先看它跑起来？克隆仓库后 npm run demo 会在示例文件上走完 改表 → 体检 → 修复 → 复验 → 输出，打印引擎的真实输出 —— 不需要模型，也不需要先装 dsh。 完整输出与上手步骤见 5 分钟上手。

_{以前这里放的是 2026-08-15 录的演示（约 v0.23），界面和操作目录都已经变了，留着会误导。 现在随版本一起更新的是 npm run demo，并且有测试钉住它的输出 （少了一个阶段、或者修复失效了，测试会红）。一版新的界面录屏欢迎贡献。}

功能实录（对话内真实截图）

下面这张是为什么敢让它动手：同一列公式，一行被静默弄坏，它指出来并修好—— 图中的异常位置、修复前后公式、健康分都是引擎真实输出。

四张截图都是 DeepSeek Harness Web 里真实模型调用工具后，在消息流工具行内 渲染出的结果：能力菜单、问题清单、可编辑表格、修复前后差异。

架构

flowchart LR
  U[用户自然语言] --> H[DeepSeek Harness]
  H --> P["excel_profile / excel_read · 结构速览 / 分页读取"]
  P --> M["excel_menu / excel_insight · 能力菜单 / 数据洞察"]
  M --> O["excel_operate / excel_task · 操作 DSL / 多步编排 / Goal 闭环"]
  O --> V["excel_validate_formulas · 公式体检"]
  V -->|异常| R["excel_autofix / excel_repair_formulas · 确定性修复 + LLM 修复"]
  V -->|干净| OUT[输出 workbook]
  R --> V2[复验]
  V2 --> OUT
  OUT --> X["excel_explain_formula / excel_diff_workbook / excel_undo · 解释 / 对比 / 可回滚"]

核心闭环：理解 → 操作 → 验证 → 修复 → 复验 → 输出；excel_task 的 goal 模式 把这条闭环升级为 Plan → Act → Observe → Verify → Replan 的 Agent 循环。

5 分钟上手

第一步：先看它做什么（不用装 dsh）

git clone https://github.com/hccccc01333/dsh-excel-chat && cd dsh-excel-chat
npm install && npm run demo

npm run demo 在示例文件的副本上跑一遍完整闭环，打印的是引擎的真实输出：

① 改表   「按区域汇总金额，输出到新表」
         销售台账-汇总：A1「区域」 B1「金额 合计」/ 华东 / 华北 / 华南 / 总计
② 体检   编辑后自动体检：87 个单元格，14 条公式 —— 检出 1 处异常
         · 销售台账!G9  [reference-offset]
③ 修复   销售台账!G9   =E9*F8  →  =E9*F9
④ 复验   异常 0 —— 公式列重新一致
⑤ 输出   repaired.xlsx + 审计日志（改前改后都在，可回滚）

注意第 ② 步：那处错误表里本来就有 —— 你只让它汇总，它顺手查了出来。 examples/sales-ledger.xlsx 就是仓库里那一份，没有任何真实业务数据—— 10 条编造的订单、3 个编造的区域。演示跑在临时副本上，仓库里的文件不会被改动。

第二步：接上对话

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

dsh plugin --profile demo add dsh-excel-chat      # 从 npm 安装
# 或从 GitHub 安装：
# dsh plugin --profile demo add github:hccccc01333/dsh-excel-chat
# 或本地 bundle 目录：
# dsh plugin --profile demo add ./bundle
dsh web --profile demo                             # 打开对话界面

_{想让我们知道有人在用？ 官方命令不上报任何东西，所以我们看不见使用者 —— 这个插件至今的公开安装计数是 0。 换成社区市场的可追踪 CLI 即可（命令与官方完全等价，只是额外上报一条匿名安装结果， 一个本地生成的安装 ID，不是账号、也不是人）：}

npx dsh1024 plugin --profile demo add dsh-excel-chat

_{它是第三方工具（MIT，源码）， 不是本项目的依赖。不想用就忽略这段，官方命令一直有效。}

装完先自检一次，确认宿主包隔离和引擎都正常：

dsh-excel-chat-doctor                              # npm 全局/npx 可用时
# 或 profile 内直接跑：
# ~/.dsh/profiles/demo/node_modules/.bin/dsh-excel-chat-doctor

把 examples/sales-ledger.xlsx 拖进对话，照着说三句，就能走完 理解 → 操作 → 验证 → 修复 → 复验 → 输出：

1. 「看一下这份台账有没有问题」——它会指出金额列里那一格公式的问题
2. 「修掉它」——修复后复验（这一步的判定是确定性的，不靠模型自我感觉）
3. 「按区域汇总金额，输出到新表」——生成汇总表，表头加粗、冻结首行

也可以换成别的说法，或者换成你自己的文件：

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

平台说明：公式校验/修复、读写单元格、样式、汇总、合并、邮件合并等功能跨平台； 图表创建/改参、原生透视表、图表 PNG 导出、PDF 导出需要 Windows + 本机安装 Excel。

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

切换输出语言（默认中文）：在 profile 的 cordis.patch.yml 里加一条覆盖—— - id: vera / config: / language: en。注意只翻译给人看的消息，工作簿里的数据 （汇总标签、生成的表名）不翻译，因为代码依赖它们。详见 docs/usage.md。

完整使用指南见 docs/usage.md，岗位用法（运营/产品/数分）见 docs/roles.md。

工具

按你想做什么分组，不是按代码模块。

先看懂文件

动手改文件

excel_operate 的 77 种操作（点开）

写值、填充/序列、行列增删、复制/移动/转置/仅粘贴值、格式刷（copyStyle）、公式转值（freezeFormulas）、唯一值提取（uniqueValues）、排名列（rankColumn）、排序（多键 / 按填充色或字体色 / 自定义序列）、report 一键报表模板（排序+汇总+动态透视+筛选+样式+冻结+格式）、分类汇总、动态透视报表、二维交叉透视表（crosstab）、两表精确关联回填（joinSheets，无公式 VLOOKUP）、高级筛选、样式（字号/字体/边框/删除线/旋转/缩进）、数据有效性、条件格式（数据条/色阶/图标集）、自动筛选、结构化表格、页面设置、页眉页脚（headerFooter）、打印分页符（rowPageBreaks）、打印标题行/列（printTitles）、命名区域、冻结/取消冻结窗格、缩放（setZoom）、网格线开关（showGridLines）、显示公式视图（showFormulas）、隐藏行列（hideRows/hideColumns）、行列分组折叠（groupRows/groupColumns）、自适应列宽（autoFitColumnWidths）、超链接（站内跳转与外部 URL）、单元格批注（addComment）、每行趋势迷你图（addSparklines）、嵌入图片（insertImage，png/jpeg/gif，可指定像素尺寸，纯 XML 层实现、跨平台不依赖 Excel）、导入/导出 CSV（importCsv/exportCsv，导出默认加公式注入防护）、查找替换、工作表保护（细化权限）、邮件合并、工作表管理（增删改名复制隐藏标签色/重排 moveSheet）、文档属性与打开时重算（setWorkbookProperties）、合并、取消全部合并（unmergeAll）、数据清洗（去重/填充缺失/删空行空列/去空格/大小写转换/全角半角标准化/分列（分隔符或固定宽度）/区域清除 clearRange）、整行条件高亮（highlightRows）、两表模糊匹配（fuzzyMatch）。

每次操作后自动复验公式并写审计日志，所以改坏了能查出来、也能回滚。

公式体检与修复（这个项目的核心）

对比与图表

评测与可靠性

能力深度与可靠性进展：144 个职场任务的自建评测语料（ExcelBench lite），覆盖 77 个操作里的 73 个， goal 模式 + glm-5.3-flash 全量实测成功率 86%（DeepSeek 基线 52%）。 逐次跑分的公开结果表见 docs/benchmark-results.md （由原始输出生成，你可以自己跑一行加进去）；指标与失败归因见 docs/benchmark.md；右侧可编辑 Excel 面板的设计与实测见 docs/web-panel.md。

一个例子：它怎么发现问题

同一列里其他行都是 =B[行]-C[行]，而 D4 写成了 =B4-C3（引用偏了一行）—— excel_validate_formulas 会把它报成 reference-offset 异常，置信度 = 多数派占比 （比如 4 行里 3 行一致，就是 0.75）。它不是「猜哪里可疑」，而是拿同一列的模式去比。

工具接受 cells（单元格映射）或 path（.xlsx 绝对路径），二者给且只给一个。

相关链接

• npm：https://www.npmjs.com/package/dsh-excel-chat
• GitHub：https://github.com/hccccc01333/dsh-excel-chat
• 版本说明：Releases · CHANGELOG
• 社区收录：awesome-dsh-plugin

已知限制

• Formula parsing is a lightweight scanner, not a full grammar: quoted strings are stripped and cell-like tokens followed by ( are treated as function names. The awkward shapes that approach invites — 1E5 ahead of a real reference, a quote doubled inside a string, LOG10 — are pinned by tests in tests/formula.test.ts rather than left to chance.
• Whole-column references (Sales!$H:$H) do not produce cell-level dependency edges.
• Range edges are enumerated only up to 10,000 cells; larger ranges contribute start/end edges only.
• The web panel edits the first sheet only. The grid library's edit event carries a row and a column but no sheet identity, and its instance exposes only the sheet it was built with. An edit made while another sheet is on screen is therefore reported against the first one. Everything reachable through the tools and the CLI is unaffected.
• Undo restores the file but not the panel. /excel-undo puts the workbook back, and the grid goes on showing the pre-undo data until the file is read again. A command result carries kind, text and sourceEventSeq and nothing else, so the panel has no channel to ask for a fresh read — closing this needs a capability the host does not expose yet.