dsh-lc-parser

外贸信用证（MT700）智能解析 — DeepSeek Harness (dsh) 双侧插件。安装完即可在 dsh Web 界面的会话视图里使用「信用证解析」标签页：上传 PDF / 粘贴报文 → 自动解析 → 三栏原文对照 → 导出 Excel / 历史回看。

能力

| 能力 | 说明 | | --- | --- | | 三通道录入 | SWIFT 报文打印件 PDF（本地提取文字层，不联网）、扫描件 PDF / 图片（走 OCR）、直接粘贴报文文本 | | 分阶段解析 | 基础信息、货物信息自动解析；商业发票 / 装箱单 / 提单 / 汇票 / 保险 5 个单据逐个点击解析；47A 公共要求与特殊提醒（十二分类） | | 原文对照 | 每个字段都带原文连续子串引用与条款号；右侧栏一键对照、整块复制，选中片段的中文翻译块默认折叠 | | 反幻觉校验 | 所有引用在本地逐字核对是否为原文连续子串；未命中的字段在界面上标记「未命中原文，请人工核实」，绝不静默放行 | | 规则校验 | 有效期窗口、假远期（含 but）、香港银行/地点、不符点费用、行总价勾稽、提单类型限制等确定性规则（代码实现，非模型猜测） | | 导出 | Excel（4 表：基础信息 / 货物信息 / 单据要求 / 公共要求与提醒，含引用与校验列）、CSV（单表含全部要点，带 BOM）、JSON（全量快照） | | 历史记录 | 保留 48 小时，到期自动清理；列表带信用证号 / 申请人 / 金额摘要 | | 中英双语 | 全部界面文案有 zh / en 两套 | | 模型工具 | 注册 lc_parse 工具，dsh agent 可在会话里直接解析信用证原文 |

环境要求

• Node.js ^22.19 或 >= 24
• pnpm >= 10
• 已全局安装 dsh CLI（>= 0.1.2-alpha.5）

安装

方式一：从本目录安装（开发 / 内网分发）

pnpm install
pnpm run build                 # 产出 lib/index.js 与 lib/client.js（含密钥门禁自检）
dsh plugin --profile web add . # 装进 web profile

方式二：从 tgz 安装包安装（推荐给使用方）

dsh plugin --profile web add ./dsh-lc-parser-0.1.2.tgz

两者都会把本包装进 $DSH_HOME/profiles/web，并把 cordis.patch.yml 的 host 插件行挂上插件树——不需要改任何配置文件。

验证安装成功

dsh --profile web --dump-config | grep -A2 lc-parser   # 应看到 host 插件行
dsh web --no-open                                      # 启动界面

启动日志里会出现一行：

[dsh-lc-parser] 已加载 (model: deepseek-flash, ocr: enabled, data: /…/.dsh/dsh-lc-parser)

打开界面后，会话视图右上方出现「信用证解析」标签页。设置 → 信用证解析设置里可以改模型与密钥。

首次配置（必读）

自 v0.1.2 起，本包不内置任何密钥（对外发布的安全要求，构建门禁强制扫描 host/client 产物）。首次使用前必须配置 DeepSeek API Key：

• 界面方式：设置 → 信用证解析设置 → 填入 apiKey（ocrUrl / ocrToken 仅扫描件 OCR 需要，可选）；
• 文件方式：写入 ~/.dsh/dsh-lc-parser/config.json（字段：apiKey / ocrUrl / ocrToken，均为可选键）。

不配置 Key 时，文字层 PDF 与粘贴文本通道可正常录入，但发起解析会提示缺少密钥。

全新机器上的首次安装

如果目标机器从未装过 dsh 的 web profile，dsh plugin --profile web add 会在初始化 profile 时拉取 @deepseek-ai/dsh-web-app，pnpm 可能因构建脚本审批而中断并提示：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: koffi@…

这是 pnpm 对传递依赖安装脚本的默认拦截（与插件本身无关）。按提示放行后重跑安装命令即可：

# 把提示里列出的包在 profile 的 pnpm-workspace.yaml 中置为 true
# 例如： allowBuilds:\n  koffi: true
dsh plugin --profile web add .   # 重跑

卸载

dsh plugin --profile web remove dsh-lc-parser
rm -rf ~/.dsh/dsh-lc-parser    # 可选：清掉历史记录与本地配置覆盖

配置

三种方式，优先级由低到高：

1. 内置默认值（src/config.ts）——安装即有可用的模型与密钥
2. cordis.patch.yml 的 config 块——批量部署时写死配置
3. 界面「设置 → 信用证解析设置」——落到 $DSH_HOME/dsh-lc-parser/config.json，最高优先级

| 键 | 默认值 | 说明 | | --- | --- | --- | | model | deepseek-flash | 解析模型。deepseek-flash（快速档）/ deepseek-v4-pro（高精度档） | | apiKey | sk-…3293（内置） | DeepSeek API Key | | baseUrl | https://api.deepseek.com | API 地址 | | ocrEnabled | true | 是否启用 OCR；关闭后仍可用 PDF 文字层与粘贴文本 | | ocrUrl | 百度 AI Studio layout-parsing | OCR 服务地址 | | ocrToken | 内置 | OCR 访问令牌 | | dataDir | $DSH_HOME/dsh-lc-parser | 历史记录与本地配置目录 | | historyTtlHours | 48 | 历史保留小时数 |

在 cordis.patch.yml 里覆盖默认值的写法：

- insert:
    - id: dsh-lc-parser
      name: dsh-lc-parser
      config:
        model: deepseek-v4-pro
        ocrEnabled: false

关于模型名

需求方原话要求的 deepseek-v4.1-flash 在 DeepSeek API 上不存在。用给定的 key 实测 GET /models 只返回 deepseek-flash 与 deepseek-v4-pro；用 deepseek-v4.1-flash 调用会被明确拒绝：

The supported API model names are deepseek-flash, deepseek-v4-pro,
but you passed deepseek-v4.1-flash

因此默认值定为同一档位的 deepseek-flash。若要改回字面名，把 model 配成任意字符串即可（不阻塞）。

关于 OCR

OCR 是回落通道，不是必经之路：

• SWIFT 报文打印件（如 T25JH052 LC.pdf，8 KB，带文字层）→ 本地 pdftext.ts 直接抽文字，不联网、不排队。信用证是商业敏感数据，少一次外呼就是少一次暴露。
• 扫描正本（如 T25JH142/165 正本LC.pdf，2.3 MB，整页位图）→ 本地抽不到可读文字，自动回落 OCR。

百度 AI Studio 端点会返回 503 + errorCode 10010「任务提交队列已满」——这是临时容量问题，插件已识别为可重试并做了 4 s / 10 s / 20 s 退避；若仍失败，界面会提示改用粘贴文本，不会误报成"配置错误"。

数据安全

• 插件只外联两个端点：api.deepseek.com（模型）与配置的 OCR 服务；其余全部本地处理。
• API Key 与 OCR token 只存在于 host 进程与磁盘配置文件，经 RPC 下发的永远是打码值（sk-********3293）。pnpm run build 内置密钥门禁：一旦密钥出现在 lib/client.js 或它的 sourcemap 里，构建立即失败退出。
• 历史记录落在 $DSH_HOME/dsh-lc-parser/sessions/，48 小时后在读取历史时惰性清理。
• 会话 id 做了字符白名单校验，杜绝路径穿越。

开发

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run test        # vitest（79 个用例，含真实 PDF 样本）
pnpm run check       # typecheck + test + build（提交前跑这个）

端到端冒烟（真实 PDF → 文字层 → 真实 LLM 解析 → 校验 → 导出）：

node --experimental-strip-types scripts/smoke.mts "D:/项目/元冰可项目/信用证信息提取/T25JH052  LC.pdf" basic,goods

目录结构

src/
├── index.ts             host 插件入口：RPC 通道 / 设置读写 / lc_parse 工具
├── config.ts            host 配置 schema（含密钥默认值，严禁进 client）
├── protocol.ts          host↔client RPC 契约（端点名与载荷类型）
├── public-defaults.ts   可进 client 的非敏感常量
├── fields.ts            字段字典与中英标签（界面与导出的唯一来源）
├── client/              浏览器侧：视图 / 控制器 / RPC 客户端 / 设置页 / 文案 / 样式
└── services/
    ├── pdftext.ts       PDF 文字层提取（零依赖）
    ├── ocr.ts           百度 layout-parsing provider
    ├── ingest.ts        三通道录入编排
    ├── deepseek.ts      OpenAI 兼容 chat/completions（超时 + 重试 + 并发上限）
    ├── prompts.ts       各阶段提示词 + 输出契约
    ├── parser.ts        分阶段编排与输出归一化
    ├── citation.ts      引用逐字校验（反幻觉核心）
    ├── validate.ts      确定性规则校验
    ├── export.ts        xlsx / csv / json 导出
    ├── xlsx.ts          零依赖 xlsx 写出
    ├── history.ts       会话落盘与 48h TTL
    └── text.ts          文本清洗、日期与金额解析

已知限制

• 解析速度取决于模型：单阶段约 15–70 s（deepseek-flash，随文本长度与负载波动）。界面按阶段串行触发，全部解析 会依次跑完 9 个阶段，属长任务。
• 中文翻译块为占位（当前无翻译服务接入），保留入口以便后续接。
• 扫描件的 OCR 准确率受百度端点排队情况影响；建议优先提供带文字层的报文打印件。
• dsh 处于 developer preview，插件按 >=0.1.2-alpha.5 声明 engines.dsh；升级 dsh 后请重跑 pnpm run check。

发布到 dsh 生态（可选）

本包已按 dsh 插件规范声明 dsh.bundle 与 dsh.client，具备直接进入生态的条件。对外发布需公司账号，步骤：

1. pnpm run check 全绿后 pnpm pack 产出 tgz
2. 在 package.json 的 keywords 中保留 dsh-plugin（已配置）——GitHub 的 dsh-plugin topic 靠它检索
3. npm publish（需要 registry 凭证）并在仓库打 dsh-plugin topic

许可

MIT