lvguqingyou/dsh-xmap

dsh-xmap

DSH（DeepSeek Harness）工具插件：把通用 Excel 读表工具 xmap 封装为模型可调用的 7 个工具。

核心思路：模型永远不 dump 整张表。模型只写一份几百字节的「列映射 spec」并查看小摘要；引擎通过 Excel COM 在模型上下文之外逐格读取整张表。表再大、版式再杂，每张表只付出「写一份 spec + 看几行摘要」的 token 成本；同版式的表用「表头指纹」自动复用 spec，模型零参与。

工具一览

| 工具 | 作用 |
|---|---|
| xmap_sheets | 列出工作簿的所有工作表（名称/行数/列数） |
| xmap_headers | 预览某张表的表头与前几行，用于理解结构 |
| xmap_hash | 表头指纹（MD5）——同指纹即同版式，用于 spec 复用 |
| xmap_extract | 按 spec 把整张表提取为标准化 JSONL（缺 spec 时按指纹自动匹配） |
| xmap_verify | 校验：记录数 + 各数值列求和（可选与表内合计行对比） |
| xmap_save_spec | 把验证过的 spec 存入 spec 库（按指纹命名） |
| xmap_aggregate | 多份 JSONL 按字段分组求和 |

环境要求

- Windows + 已安装 Microsoft Excel（引擎使用 Excel COM）。
- DeepSeek Harness：在当前产品代（DSH 0.1.3-alpha.1 系列 / cordis 4.0.x）上开发与验证。API 在旧版/未来版本宿主上可能有差异。
- PowerShell：优先 pwsh，没有时自动回退 Windows PowerShell 5.1。
- 工具调用沿用会话沙箱策略；跨工作区写文件时按宿主惯例提供 sandbox_permissions + justification。

安装

从 npm（发布后）或本地目录均可：

方式一：npm 包（发布后可用）
dsh plugin --profile web add dsh-xmap

方式二：从源码目录
git clone https://github.com/lvguqingyou/dsh-xmap.git   # HTTPS 不通时可用 SSH：git@github.com:lvguqingyou/dsh-xmap.git
dsh plugin --profile web add

装完重启 dsh web（新增 bundle 不热生效），之后工具即出现在模型工具表中。

用法示例

1) 看有哪些表
xmap_sheets file="C:\data\book.xlsx"
2) 看某张表结构
xmap_headers file="C:\data\book.xlsx" sheet="Sheet1" rows=5
3) 提取 → JSONL
xmap_extract file="C:\data\book.xlsx" sheet="Sheet1" out="C:\data\records.jsonl"
4) 校验
xmap_verify file="C:\data\book.xlsx" sheet="Sheet1" spec="C:\spec.json" records="C:\data\records.jsonl"
5) 跨表聚合
xmap_aggregate records="C:\a.jsonl,C:\b.jsonl" groupBy="name" sum="amount" out="agg.jsonl"

Spec 格式与完整命令说明见 xmap/README.md（含 headerRows / dataStart / cols / numeric / skipIfNameEmpty / checkTotal）。

配置（cordis.yml 的 config:）

| 键 | 含义 | 默认 |
|---|---|---|
| specDir | spec 库目录；留空用包内自带 xmap/specs | 包内 specs |
| timeoutMs | 单次 Excel COM 前台超时（毫秒） | 300000 |

本地开发

node scripts/smoke.mjs   # 桩 ctx 冒烟：7 工具注册 / 命令构造 / 结果映射（不碰 Excel、不碰 GUI）

从源码目录安装（link: 方式）时，Node 按真实路径解析模块，需要把 DSH 模块库的包链接到本目录（Windows junction / 符号链接），缺失会报找不到 @deepseek-ai/...：

node_modules/@deepseek-ai/  ->  %USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\

需要的包：schemastery、dsh-tools、dsh-sandbox（cordis 由宿主导入）。改代码后无需重装，但需重启 dsh web 生效。

安全提示

插件通过宿主 ctx.shell 执行本包内的 xmap/xmap.ps1；请从可信来源安装，并在安装前检查来源（第三方插件在你的机器上以你的权限运行）。