光伏储能方案生成AlanHuang168/dsh-ess-proposal

dsh-ess-proposal

根据电费单一键生成「光伏 + 储能」方案的 DSH 插件（马来西亚市场）
A DSH plugin that turns an electricity bill into a solar + energy-storage proposal (Malaysia)

DSH Plugin
TypeScript
Vision
LLM
License

简体中文 ｜ English

目录

- 简介
- 效果预览
- 特性
- 工作原理
- 目录结构
- 安装
- 配置
- 使用
- 输出示例
- 数据与假设
- 开发
- Roadmap
- 许可证

简介

dsh-ess-proposal 是一个 DSH（DeepSeek Harness）插件，基于 @deepseek-ai/cordis 构建。它在 DSH 对话中注册一个 generate_ess_proposal 工具：上传一张马来西亚 TNB 电费单图片，即可自动提取用电数据 → 推荐光伏/储能配置 → 测算投资、回收期与 ROI，并给出结构化结果。

⚙️ 视觉提取优先使用阿里云百炼 Qwen-VL，失败时回退到本地 OCR + DeepSeek 文本结构化，再兜底正则解析。

🖼️ 效果预览

效果截图

✨ 特性

- 📄 电费单识别 — 传入电费单图片本地路径，自动提取峰谷用电量、最大需量、电费总额、电价代码
- 🧠 多级提取，稳健兜底 — Qwen-VL 看图 → 本地 OCR + DeepSeek → 正则回退，尽量拿到可用数据
- 🧮 确定性测算 — 光伏容量、储能容量、投资、年/月节省、回收期、ROI、年减碳量，全部由代码计算（非模型臆测）
- 🇲🇾 本地化假设 — 造价、发电量、电网碳因子等假设集中在 data/tariff.json，并支持升级安全的用户目录覆盖（见「配置」）
- 🏠 分客户类型策略 — residential / commercial / factory / datacenter 采用不同的储能与自用率逻辑
- 🧩 结构化输出 — 返回 summary + extracted_data + recommended_config + financial + assumptions + risks

🏗️ 工作原理

generate_ess_proposal(customer_type, location, bill_images, …)
│
▼
提取电费数据 extractBillData()
├─ 1) Qwen-VL 看图 (qwen-vl-plus, DashScope)      ← prompt/extract-qwen-vl.md
├─ 2) 回退：本地 OCR（可选，需 DSH_ESS_OCR_BIN）
│        └─ DeepSeek 结构化 (deepseek-v4-flash)   ← prompt/extract-ocr-llm.md
└─ 3) 兜底：正则解析
▼
方案计算 buildProposal()   ← 假设来自 data/tariff.json
│   (PV 容量 / 储能 / 投资 / 回收期 / ROI / 减碳)
▼
结构化返回 (summary + extracted_data + recommended_config + financial + assumptions + risks)

📦 目录结构

dsh-ess-proposal/
├── README.md                     # 本文档（双语）
├── License                       # MIT
├── package.json                  # 依赖、脚本、bundle.patch
├── tsconfig.json
├── cordis.patch.yml              # DSH 插件声明
├── src/index.ts                  # 插件主逻辑（工具注册 + 提取 + 测算）
├── dist/                         # 构建产物（tsc）
├── prompt/
│   ├── extract-qwen-vl.md        # Qwen-VL 看图提取提示词
│   └── extract-ocr-llm.md        # OCR 文本 → DeepSeek 结构化提示词
├── data/
│   ├── tariff.json               # 造价/发电/碳因子等默认假设
│   ├── product-catalog.json      # 产品目录（占位，待补充）
│   └── policy-notes.md           # 政策要点（占位，待补充）
├── test_cases/                   # 示例电费单图片（已脱敏）
├── 1.png                         # 效果截图
├── 2.png / 3.png                 # 安装截图 / 插件市场搜索
├── .env.example                  # 环境变量模板
└── .gitignore

📥 安装

从插件市场安装
dsh plugin --profile web add dsh-ess-proposal

或本地路径安装
dsh plugin --profile web add /path/to/dsh-ess-proposal

安装截图

安装后在 Settings → Plugins → Plugin list 搜索 dsh-ess 即可确认，Cordis status: Mounted 表示挂载成功：

插件市场搜索

⚙️ 配置

API Key

Key 在插件加载时从 process.env 读取。改动 Key 后需重启 dsh 并开新的 Session 才会生效。

① 市场 / npm 安装（推荐用环境变量）

插件装在 profile 的 node_modules/ 里，不要在包内新建 .env（升级会丢）、也无需手动改 cordis.patch.yml（插件清单随包发布，安装时自动 Mounted）。在启动 dsh 的 shell 里导出环境变量即可：

插件市场搜索

export DASHSCOPE_API_KEY=sk-your-bailian-key    # 阿里云百炼，Qwen-VL 看图（强烈建议）
export DEEPSEEK_API_KEY=sk-your-deepseek-key    # DeepSeek，OCR 文本结构化回退（可选）

dsh --profile web                               # 之后（重新）启动 dsh，开新 Session

必须在启动 dsh 之前导出（否则插件加载时读不到）。环境变量优先级高于 .env。持久化可写入 ~/.zshrc / ~/.bashrc。

② 本地开发（源码目录）

cp .env.example .env

DASHSCOPE_API_KEY=sk-your-bailian-key
DEEPSEEK_API_KEY=sk-your-deepseek-key

🔒 .env 已在 .gitignore 中，切勿提交真实密钥。此方式仅在从源码目录挂载时有效（.env 与包同目录）。

缺 Key 时会怎样

不会崩溃，按下表逐级降级：

| 情况 | 行为 |
|------|------|
| 有 DASHSCOPE_API_KEY | Qwen-VL 看图提取（最佳路径） |
| 无 DASHSCOPE、有 DEEPSEEK_API_KEY | 跳过 Qwen →（如配置了 DSH_ESS_OCR_BIN）本地 OCR → DeepSeek 结构化；否则直接正则兜底 |
| 两个都没有 | 跳过 Qwen →（如有 OCR）本地 OCR → 正则兜底；识别质量明显下降 |
| 完全提取不到数据 | 返回经验默认配置，missing_info 提示「未能从账单提取用电量」 |

⚠️ 非 macOS 且无 DASHSCOPE_API_KEY 时，OCR 回退不可用，基本无法从图片提取数据 —— 请至少配置 DASHSCOPE_API_KEY。缺 Key 时终端会打印 未配置 XXX_API_KEY，跳过 … 的提示。

自定义电价 / 造价假设（升级安全）

不要直接改包内 data/tariff.json（升级会被覆盖）。把覆盖文件放到用户目录：

mkdir -p ~/.dsh/dsh-ess-proposal
cat > ~/.dsh/dsh-ess-proposal/tariff.json  覆盖为浅合并，只写想改的字段即可，其余沿用默认。改完同样需重启 dsh / 开新 Session。
生效顺序（后者覆盖前者）：硬编码默认 → 包内 data/tariff.json → ~/.dsh/dsh-ess-proposal/tariff.json → DSH_ESS_TARIFF_PATH。

🚀 使用

在 DSH 对话中调用 generate_ess_proposal：
text
请使用 generate_ess_proposal：
- customer_type: residential
- location: Selangor
- bill_images: ["/path/to/bill.jpg"]

工具参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| customer_type | string | ✅ | residential / commercial / factory / datacenter |
| location | string | ✅ | 客户所在地，如 Selangor、Johor、Kuala Lumpur |
| target_payback_years | number | | 目标回收期（年），默认 5 |
| special_requirements | string | | 特殊要求（如含「储能/battery」会强制配置储能） |
| bill_images | string[] | | 电费单图片本地路径列表 |
| site_images | string[] | | 现场照片本地路径列表 |

📤 输出示例
jsonc
{
"summary": "已解析电费单：月用电 900 kWh、月电费 RM 479.30。推荐 8 kWp 光伏（暂不配储能），预计投资 RM 34,400，回收期约 6.5 年。（提取方式: qwen-vl）",
"extracted_data": {
"tariff_code": "A",
"peak_kwh": 500, "offpeak_kwh": 400, "total_kwh": 900,
"max_demand_kw": 0, "total_bill_myr": 479.30,
"extract_method": "qwen-vl"
},
"recommended_config": { "pv_kwp": 8, "storage_kw": 0, "storage_kwh": 0, "notes": ["…"] },
"financial": {
"estimated_investment": 34400, "annual_saving": 5280, "monthly_saving": 440,
"payback_years": 6.5, "roi": 15.3, "co2_reduction_kg_per_year": 6501
},
"assumptions": { "solar_cost_rm_per_kwp": 4300, "effective_tariff_rm_per_kwh": 0.533, "…": "…" },
"risks": ["实际发电量受屋顶朝向/遮挡影响，需现场勘察确认最终装机"]
}

上述数值为示例，实际以你的电费单与 data/tariff.json 假设为准。

📊 数据与假设

方案测算的关键假设集中在 data/tariff.json 的 defaults：

| 键 | 默认值 | 含义 |
|----|-------|------|
| solar_cost_rm_per_kwp | 4300 | 光伏造价（RM/kWp） |
| battery_cost_rm_per_kwh | 1800 | 储能造价（RM/kWh） |
| pv_yield_kwh_per_kwp_year | 1400 | 光伏年发电量（kWh/kWp·年） |
| grid_emission_kg_per_kwh | 0.581 | 电网碳因子（kg CO₂/kWh） |
| fallback_rate_rm_per_kwh | 0.55 | 无法从账单推算电价时的兜底电价 |

⚠️ 以上为马来西亚市场默认假设，用于量级测算，不构成报价承诺；正式方案请按本地实际造价与 TNB 电价核对。

🛠️ 开发

npm install
npm run build          # tsc 编译到 dist/
npm run dev            # tsx 直接运行 src/index.ts

本地挂载调试
dsh plugin --profile web add .
dsh --profile web

🧩 插件清单约定：本包在 package.json 用 "bundle": { "patch": "./cordis.patch.yml" } 声明补丁，当前 dsh CLI 据此挂载成功。若你的 harness 版本约定的是 "dsh": { "bundle": … }，请以该版本 CLI/官方文档为准同步此字段。

🗺️ Roadmap

- [x] Qwen-VL 看图 + OCR/DeepSeek 回退 + 正则兜底
- [x] 确定性方案测算（PV/储能/投资/回收期/ROI/减碳）
- [ ] 补全 data/product-catalog.json，让选型落到真实型号（并支持与 tariff.json 相同的用户目录覆盖）
- [ ] 补全 data/policy-notes.md（NEM 3.0 / 最大需量 / GITA）
- [ ] 峰谷套利与需量优化的储能策略细化
- [ ] 接入跨平台 OCR 回退（如 tesseract）；当前开源版不内置 OCR 二进制，可用 DSH_ESS_OCR_BIN 自备

🤝 贡献

欢迎提 Issue 与 PR。建议为 GitHub 仓库打上 dsh-plugin topic。

📄 许可证

本项目基于 MIT License 开源。

🌏 English

简体中文 ｜ English

Overview

dsh-ess-proposal 是一个 DSH（DeepSeek Harness）插件，基于 @deepseek-ai/cordis 构建。它在 DSH 对话中注册了一个 generate_ess_proposal 工具：上传一张马来西亚 TNB 电费单图片，它会自动提取用电数据 → 推荐光伏/储能配置 → 估算投资、回收期与 ROI，并返回结构化结果。

⚙️ 视觉提取优先使用阿里云百炼 Qwen-VL，回退到本地 OCR + DeepSeek 文本结构化，最后使用正则解析器。

Screenshot

screenshot

Features

- 📄 账单解析 — 从本地账单图片路径提取：峰/谷 kWh、最大需量、总费用、电价代码
- 🧠 稳健的多阶段提取 — Qwen-VL → 本地 OCR + DeepSeek → 正则兜底
- 🧮 确定性经济测算 — 光伏/储能容量配置、投资、月度/年度节省、回本周期、ROI 和 CO₂ 减排量全部由代码计算（而非模型猜测）
- 🇲🇾 本地化假设 — 成本、发电量和电网排放因子存放在 data/tariff.json 中，并支持升级安全的用户目录覆盖（见配置章节）
- 🏠 分场景策略 — 住宅 / 商业 / 工厂 / 数据中心采用不同的储能与自消费逻辑
- 🧩 结构化输出 — summary + extracted_data + recommended_config + financial + assumptions + risks

工作原理

generate_ess_proposal(customer_type, location, bill_images, …)
│
▼
extractBillData()
├─ 1) Qwen-VL 视觉识别（qwen-vl-plus，DashScope）      ← prompt/extract-qwen-vl.md
├─ 2) 回退：本地 OCR（可选，DSH_ESS_OCR_BIN）
│        └─ DeepSeek 结构化（deepseek-v4-flash） ← prompt/extract-ocr-llm.md
└─ 3) 最后手段：正则解析器
▼
buildProposal()   ← 假设来自 data/tariff.json
▼
结构化结果（summary + extracted_data + recommended_config + financial + assumptions + risks）

安装

dsh plugin --profile web add dsh-ess-proposal        # 从 registry 安装
dsh plugin --profile web add /path/to/dsh-ess-proposal   # 本地路径

install

在 Settings → Plugins → Plugin list 中搜索 dsh-ess 进行验证 — Cordis status: Mounted 表示已加载：

plugin list

配置

配置项在插件加载时从 process.env 读取。修改配置项后，需重启 dsh 并打开新的 Session 才能生效。

① 应用市场 / npm 安装（使用环境变量）

插件位于 profile 的 node_modules/ 下。不要在包内创建 .env（升级时会丢失），也无需修改 cordis.patch.yml（清单随包一起发布并自动挂载）。在启动 dsh 的 shell 中导出这些变量：

export DASHSCOPE_API_KEY=sk-your-bailian-key    # 阿里云百炼，Qwen-VL 视觉识别（强烈推荐）
export DEEPSEEK_API_KEY=sk-your-deepseek-key    # DeepSeek，OCR 文本结构化回退（可选）

dsh --profile web                               # 然后（重新）启动 dsh，打开新的 Session

请在启动 dsh 之前导出这些变量（否则插件在加载时无法读取它们）。环境变量优先于 .env。可将它们持久化到 ~/.zshrc / ~/.bashrc。

② 本地开发（源码检出）

cp .env.example .env

DASHSCOPE_API_KEY=sk-your-bailian-key
DEEPSEEK_API_KEY=sk-your-deepseek-key

🔒 .env 已被 git 忽略 — 切勿提交真实密钥。此方式仅在从源码检出挂载时有效（.env 与包位于同一目录）。

缺少密钥时会发生什么

它不会崩溃 — 而是逐步降级：

| 情况 | 行为 |
|-----------|----------|
| DASHSCOPE_API_KEY 已设置 | Qwen-VL 视觉提取（最佳路径） |
| 无 DASHSCOPE，但有 DEEPSEEK_API_KEY | 跳过 Qwen → 本地 OCR（可选，设置 DSH_ESS_OCR_BIN）→ DeepSeek 结构化；否则直接使用正则 |
| 两个密钥都没有 | 跳过 Qwen → 本地 OCR（如已配置）→ 正则回退；质量明显较低 |
| 无可提取内容 | 返回默认配置，并附带 missing_info 说明 |

⚠️ 在非 macOS 系统上且没有 DASHSCOPE_API_KEY 时，OCR 回退不可用，图像提取基本会失败——至少需设置 DASHSCOPE_API_KEY。缺少密钥时会在终端打印 未配置 XXX_API_KEY, 跳过 … 警告。

自定义电价 / 成本假设（升级安全）

请勿编辑随附的 data/tariff.json（升级时会被覆盖）。将覆盖文件放在你的用户目录中：

mkdir -p ~/.dsh/dsh-ess-proposal
cat > ~/.dsh/dsh-ess-proposal/tariff.json  覆盖是浅合并——只需设置你想更改的字段。编辑后重启 dsh / 打开新会话。
优先级（后者优先）：硬编码默认值 → 随附的 data/tariff.json → ~/.dsh/dsh-ess-proposal/tariff.json → DSH_ESS_TARIFF_PATH。

用法

在 DSH 对话中调用 generate_ess_proposal：
text
Use generate_ess_proposal:
- customer_type: residential
- location: Selangor
- bill_images: ["/path/to/bill.jpg"]

| 参数 | 类型 | 必填 | 描述 |
|-----------|------|:--------:|-------------|
| customer_type | string | ✅ | residential / commercial / factory / datacenter |
| location | string | ✅ | 客户所在地，例如 Selangor |
| target_payback_years | number | | 目标回本年限（年），默认 5 |
| special_requirements | string | | 自由文本（提及“battery/storage”会强制进行储能容量配置） |
| bill_images | string[] | | 账单图像的本地路径 |
| site_images | string[] | | 现场照片的本地路径 |

数据与假设

关键假设位于 data/tariff.json 的 defaults 中：solar_cost_rm_per_kwp（4300）、battery_cost_rm_per_kwh（1800）、pv_yield_kwh_per_kwp_year（1400）、grid_emission_kg_per_kwh（0.581）、fallback_rate_rm_per_kwh（0.55）。

⚠️ 这些是用于数量级估算的马来西亚默认值——并非价格承诺。在任何真实提案之前，请根据当地成本和 TNB 电价进行核实。

开发
bash
npm install
npm run build          # tsc → dist/
npm run dev            # tsx src/index.ts
dsh plugin --profile web add .
dsh --profile web

🧩 清单约定：此包通过 package.json 中的 "bundle": { "patch": "./cordis.patch.yml" } 声明其补丁，当前 dsh CLI 可成功挂载该补丁。如果你的工具链版本期望的是 "dsh": { "bundle": … }，请将此字段与该版本的 CLI / 官方文档保持一致。

许可证

基于 MIT 许可证 发布。