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-xmap 目录>

装完重启 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/<pkg>  ->  %USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\<pkg>

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

安全提示

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