dsh-excel-chat — 和 Excel 对话，把活干完 在 DeepSeek Harness 里用自然语言 操作 Excel：说一句“给 D 列加毛利公式、表头加粗、冻结首行、加筛选”，agent 会自动 调用 excel_operate 完成；每次编辑后自动体检公式有没有被弄坏，也可以让它 “检查这个表哪里算错了”并自动修复。所有工作都在对话里完成，不需要记 Excel 操作。 ## 功能实录（对话内真实截图） | 能力菜单：给文件就给你选项 | 数据洞察：自动发现数据问题 | | --- | --- | | | | | 表格预览：对话内真网格 | 公式体检 + 自动修复：差异一目了然 | | --- | --- | | | | 四张截图都是 DeepSeek Harness Web 里真实模型调用工具后，在消息流工具行内 渲染出的结果：能力菜单、问题清单、可编辑表格、修复前后差异。 ## 架构 mermaid 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 循环。 ## 安装 sh dsh plugin --profile demo add dsh-excel-chat # 从 npm 安装 dsh plugin --profile demo add ./bundle # 或本地 bundle 目录 装完先自检一次，确认宿主包隔离和引擎都正常： sh dsh-excel-chat-doctor # npm 全局/npx 可用时 # 或 profile 内直接跑： # ~/.dsh/profiles/demo/node_modules/.bin/dsh-excel-chat-doctor 装完直接聊，例如： > 帮我把 report.xlsx 做成报表：D 列是毛利（收入减成本），E 列加合计， > 表头加粗填浅灰，冻结第一行，加筛选。 > 检查 sales.xlsx 里 D 列公式是不是每行都是“收入-成本”，不对的帮我修掉。 完整使用指南见 docs/usage.md，岗位用法（运营/产品/数分）见 docs/roles.md。 ## 给使用者：一分钟上手 前提：已安装 DeepSeek Harness（dsh CLI 或桌面端）。 sh dsh plugin --profile demo add dsh-excel-chat # 从 npm 安装 # 或从 GitHub 安装： # dsh plugin --profile demo add github:hccccc01333/dsh-excel-chat dsh web --profile demo # 打开对话界面 然后在对话里直接说： - “帮我把 report.xlsx 做成报表：D 列毛利、E 列合计、表头加粗、冻结首行、加筛选” - “检查 sales.xlsx 的 D 列公式有没有错，不对的修掉” - “按区域生成透视表，金额合计，再生成柱状图” 平台说明：公式校验/修复、读写单元格、样式、汇总、合并、邮件合并等功能跨平台； 图表创建/改参、原生透视表、图表 PNG 导出需要 Windows + 本机安装 Excel。 锁定版本：dsh plugin --profile demo add dsh-excel-chat@0.23.0（不写版本默认 latest）。 ## 工具 | 工具 | 作用 | |---|---| | excel_validate_formulas | 静默公式错误检测：列 pattern 偏移、结构不匹配、hardcode、空行、循环引用、#REF!/#DIV/0! 等错误值 | | excel_compile_formula | Formula IR（binary / ratio / aggregate / function：VLOOKUP、IF、XLOOKUP、统计、日期等）→ 确定性 Excel 公式 | | excel_read | 精确读取：值/公式/类型/数字格式/字体/填充/对齐/合并/数据有效性，编辑前看清单元格状态 | | excel_profile | 大表速览：识别表头、每列类型/缺失/唯一值/数值区间/高频值/样例，给出建议读取范围；配合 excel_read 的 maxRows 分页，避免整表灌入对话爆 token | | excel_semantic_profile | 语义画像：把每列分类为 时间/维度/指标/标识，识别数据粒度、派生指标（公式）和跨表关联键；分析类任务先跑它，agent 不再猜“地区是不是 B 列” | | excel_menu | 不会描述也没关系：给文件就能拿到菜单——一句话总结表里有什么，再列出清洗/补空值/报表/透视/图表/体检/通知/岗位模板等可选方案，每个带示例话术，直接选就行 | | excel_insight | 数据洞察：一句话摘要 + 缺失/重复/异常值/负值/空格/公式等启发式体检 + 下一步建议，回答“这表有什么问题”“帮我总结一下” | | excel_preview | 表格预览：把指定表/区域渲染成 Markdown 表格（对话内直接看到）+ HTML 预览文件，回答“看看这个表长什么样” | | excel_task | 两种模式：steps 多步编排（每步自动体检公式、坏了自动修）；goal Agent 闭环（LLM 规划步骤 → 执行 → 验证 → 未达成自动重规划，最多 maxRounds 轮） | | excel_explain_formula | 公式白话解释：解析函数（SUMIFS/VLOOKUP/IF/日期/文本/统计）、引用区域、跨表引用，回答“这个公式是什么意思” | | excel_undo | 按 excel_operate 自动生成的 .patch.json 审计日志回滚编辑 | | excel_repair_formulas | 确定性修复 + 可选 LLM 修复（useLlm / autoTable / oraclePath / outPath），输出修复副本并复验 | | excel_autofix | 一键自愈闭环：体检 → 确定性修复（可选 LLM）→ 复检 → 人话汇报，输出修复副本（自动附带隐藏健康报告表，可 healthReport:false 关闭） | | excel_health_report | 把公式体检报告写进工作簿本身：隐藏「_dsh_体检报告」表，含健康分、异常清单、生成时间，报告跟着文件走 | | excel_diff_workbook | 两个 workbook 的单元格级 diff | | excel_operate | 精细化 Excel 操作：写值、填充/序列、行列增删、复制/移动、排序、report 一键报表模板（排序+汇总+动态透视+筛选+样式+冻结+格式）、分类汇总、动态透视报表、高级筛选、样式（字号/字体/边框）、数据有效性、条件格式（数据条/色阶/图标集）、自动筛选、结构化表格、页面设置、命名区域、冻结窗格、查找替换、工作表保护（细化权限）、邮件合并、工作表管理、合并、数据清洗（去重/填充缺失/删空行空列/去空格/大小写转换/全角半角标准化/分列）、整行条件高亮（highlightRows）、两表模糊匹配（fuzzyMatch）；操作后自动复验公式并写审计日志 | | excel_validate_charts | 图表结构校验：类型、系列、缺失单元格、二维范围、日期排序 | | excel_validate_charts_visual | Excel 导出 PNG + 视觉 LLM 评审 | | excel_export_charts | 用本地 Excel 把图表导出为 PNG（Windows） | | excel_create_chart | 用本地 Excel 创建图表：数据范围、类型、标题（Windows） | | excel_modify_chart | 修改图表参数：类型、标题、图例、坐标轴（Windows） | | excel_create_pivot | 原生数据透视表（pivotCache + pivotTable）：多行字段、列字段、报表筛选器 + 值字段（求和/计数/平均/最大/最小），Excel 生成、可刷新（Windows） | 能力深度与可靠性进展：100 个职场任务的自建评测语料（ExcelBench lite）与 真实 LLM 基线见 docs/benchmark.md；右侧可编辑 Excel 面板的设计与实测见 docs/web-panel.md。 ## Modules - src/formula.ts — A1 reference parser (cell, range, cross-sheet, whole-column), canonical cell ids, column helpers. - src/graph.ts — dependency graph with bounded range expansion and cycle detection. - src/patterns.ts — per-column reference-pattern analysis: offset anomalies, structure mismatches, hardcode breaks, empty gaps. - src/validator.ts — validate(cells) entry point returning graph + column reports + anomalies. - src/ir.ts — Formula IR 类型（binary / ratio / aggregate）。 - src/ir-schema.ts — Formula IR 的 dsh 工具 DSL schema（严格 oneOf 校验）。 - src/compiler.ts — compileFormula(ir, { baseCell, table }) 编译为 Excel 公式。 - src/advisor.ts — LLM 修复顾问：异常 + 表结构 → prompt → IR 修复 → Patch。 - src/llm.ts — llmTextFromContext：把 ctx.llm 流式服务接入修复顾问（可选注入）。 - src/diff.ts — Workbook Diff 与 Patch Log：diff / apply / rollback。 - src/charts.ts / src/chart-validator.ts — xlsx 图表 XML 解析与结构校验。 - src/chart-visual.ts — Excel COM 图表创建/参数修改/导出 + 可注入视觉评审（VLM 接口）。 - src/vision.ts — visionTextFromContext：把 ctx.attachments + ctx.llm 接成视觉评审。 - src/deepseek.ts — DeepSeek chat completions 客户端（读 DEEPSEEK_API_KEY），接修复顾问。 - src/patch.ts — 最小补丁抽象：apply / revert / 写回 workbook。 - src/repair.ts — 从验证结果生成确定性修复（引用偏移 + 空行填充），写出 .repaired.xlsx 并复验；可选传入 oracle cells 返回 oracleScore。 - src/workbook.ts — ExcelJS-based workbook reader: .xlsx → cell-content map, and validateWorkbookFile(path). - src/tables.ts — detectTableFromCells：从单元格内容推断 { sheet, columns }， 供 excel_repair_formulas 的 autoTable 自动识别表头。 - src/score.ts — scoreWorkbookAgainstOracle：oracle 单元格级判分，容忍公式 大小写/空白与数字格式差异，输出准确率与 mismatch 明细。 - src/read.ts — readWorkbookDetail：精确读取单元格（值/公式/类型/格式/合并/ 数据有效性），供 excel_read 工具使用。 - src/profile.ts — profileWorkbook：结构化表格编码，输出每表/每列的 紧凑画像与建议读取范围，供 excel_profile 工具使用。 - src/autofix.ts — autofixWorkbookFile：体检 → 修复 → 复检 → 人话总结的 一键自愈闭环，供 excel_autofix 工具使用。 - src/pivot.ts — createPivotTable：驱动 Excel COM 生成原生数据透视表 （pivotCache + pivotTable），保证文件始终合法可打开。 - src/operation-schema.ts — excel_operate 的 27 操作严格判别联合 schema， 让模型按 op 字段直接生成正确结构。 - src/operations.ts — Excel 操作 DSL：set（自动类型识别）/ fill / fillSeries / insertRows / deleteRows / insertColumns / deleteColumns（公式引用联动，含跨表， 被删单元格引用转 #REF!）/ sortRange（多键排序）/ copyRange / moveRange / style / dataValidation（下拉与数值校验）/ conditionalFormatting / setColumnWidth / autoFilter / addTable（结构化表格）/ setRowHeight / freezePanes / findReplace / addSheet / renameSheet / deleteSheet / duplicateSheet / hideSheet / setTabColor / clear / merge / unmerge。 - src/benchmark.ts — Pass@1 benchmark：确定性修复 → LLM 修复，与 oracle 对比判分。 - src/benchmark-cases.ts — 11 个 benchmark 任务：范围端点、绝对引用、空行、 跨表、多表、聚合结构、hardcode 等场景。 - src/file-benchmark.ts + src/corpus/ — ExcelBench lite：100 个文件级真实 职场任务（编辑/分析/公式/工作流），运行与指标见 docs/benchmark.md。 - src/index.ts — dsh plugin entry exposing eight tools（validate / compile / repair / diff / operate / chart structure / chart export / chart visual）。 - bundle/ — 可发布 dsh bundle：manifest + cordis.patch.yml + 编译产物。 ## Run tests sh node --test tests/formula-validator.test.ts node --test tests/compiler.test.ts node --test tests/workbook-reader.test.ts node --test tests/patch.test.ts node --test tests/repair.test.ts node --test tests/ir-schema.test.ts node --test tests/advisor.test.ts node --test tests/llm-wiring.test.ts node --test tests/diff.test.ts node --test tests/chart-validator.test.ts node --test tests/load-bundle.test.ts node --test tests/chart-visual.test.ts node --test tests/pack-bundle.test.ts node --test tests/vision-wiring.test.ts node --test tests/deepseek.test.ts node --test tests/tables.test.ts node --test tests/score.test.ts node --test tests/benchmark.test.ts 真实模型端到端： sh node tests/invoke-real-llm.ts node tests/invoke-conversation.ts # 对话直用：自然语言 -> 工具调用 -> 执行 -> 复验 Pass@1 benchmark（确定性修复 + 可选 LLM）： sh node tests/invoke-benchmark.ts # 仅确定性路线 VERA_BENCH_LLM=1 node tests/invoke-benchmark.ts # 接真实 DeepSeek 构建并安装 bundle： sh npm run build:bundle dsh plugin --profile demo add ./bundle 发布 bundle（可选，本地打包）： sh cd bundle && npm pack 自动发布（GitHub Actions，需在仓库配置 NPM_TOKEN 自动化 token）： sh git tag v0.18.0 && git push origin v0.18.0 CI 会执行测试、构建、npm pack 校验 tag 与版本一致、发布 npm，并在 GitHub Release 上附带 tarball。 通过真实执行管线调用工具： sh node --import tsx tests/invoke-plugin.ts node --import tsx tests/invoke-compiler.ts node --import tsx tests/invoke-workbook.ts node --import tsx tests/invoke-repair.ts 挂进 Web UI（可选，两种方式）： sh # 方式一：从仓库目录启动，patch 指向本目录 pnpm dsh web --patch D:/vera/cordis.yml # 方式二：安装官方 CLI 后从本目录启动（依赖树较大，机器空闲时再装） npm install --save-dev @deepseek-ai/dsh@0.1.0-rc.6 npx dsh web --patch D:/vera/cordis.yml Windows 上 cordis.yml 的入口路径必须是 file:///D:/vera/src/index.ts 形式的 URL。 ## Example D4 = B4-C3 inside a column where every other row is =B[row]-C[row] is reported as a reference-offset anomaly with confidence = majority support fraction (e.g. 3/4 = 0.75). The tool accepts either cells (a map) or path (an absolute .xlsx path) — exactly one. ## 相关链接 - npm：https://www.npmjs.com/package/dsh-excel-chat - GitHub：https://github.com/hccccc01333/dsh-excel-chat - 社区收录：awesome-dsh-plugin ## Known limitations (P0) - Formula parsing is a lightweight scanner, not a full grammar: quoted strings are stripped, cell-like tokens followed by ( are treated as function names, and exotic constructs (e.g. 1E5 inside an expression before a real cell ref) may still mis-parse. - 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.