前言¶
在 DSH（DeepSeek Harness）里做个人财务相关的工作流时，常见做法是把支出记进表格或外部 App，再另开渠道查基金收益；会话里看到的数字往往来自不同来源，还容易把「可支配现金」和「持仓盈亏」混在一起。下面介绍 maintainer ainachoneko 发布的 dsh-ledger-wealth：DeepSeek Harness 分类为「工作流」的插件，把「今天花了多少」和「理财今天赚了多少」放进同一会话，但两笔钱始终是两本账——分表存储、分节汇报，任何地方都不相加。数据落在本机 SQLite，不经过自有服务器。
这是什么¶
dsh-ledger-wealth 是本地优先的记账 + 理财持仓 DSH 插件：支持记账与小票 OCR、running balance、收益严格降级链、月末双节报告（英文简介：Local-first bookkeeping + wealth ledger for DeepSeek Harness）。
- 仓库：ainachoneko/dsh-ledger-wealth
- 社区目录页：skillhub 插件页
- 当前
package.json版本：1.0.0，许可证 MIT - 运行要求：Node >=22.5.0，DSH >=0.2.1-rc.1 <0.3.0-0
核心设计：两模块、物理隔离¶
插件把能力拆成 A 记账 与 B 理财，在数据层用不同表隔离：
| 模块 | 能力概要 |
|---|---|
| A 记账 | 一句话或一张小票 → 结构化账目 → 用户确认后落库；余额 = 初始余额 + 累计收入 − 累计支出；月末报告含支出、收入、净结余、分类占比（前 5）、最大单笔、环比 |
| B 理财 | 持仓录入 → 每日收益按严格降级链取数，每个数字带来源标注；月末理财报告单独一节 |
物理隔离：ledger_entries 与 wealth_* 分表；finance_monthly_report 用分隔线切开记账与理财，没有跨模块合计。金额在库内以整数分（*_cents）存储，对外 JSON 和文案再转为「元 + 两位小数」。
记账工具（A）¶
安装后注册约 20 个工具。与记账直接相关的包括：
| 工具 | 作用 |
|---|---|
ledger_set_initial_balance |
设置初始余额（必填，不会默认按 0 处理） |
ledger_add_entry |
记一笔：先预览，confirm:true 才落库 |
ledger_list_entries |
按月份/类型列账目 |
ledger_delete_entry |
删账目：先预览，confirm:true 才删 |
ledger_balance |
当前可支配余额 + 本月收支 |
ledger_month_summary |
月度汇总：分类占比、最大单笔、每日明细 |
ledger_scan_receipt |
小票图片 → 草稿（识别不到就留空，不猜） |
典型流程：先 ledger_set_initial_balance 设期初，日常用 ledger_add_entry 记收支；有小票时用 ledger_scan_receipt 出草稿，再在确认后落库。安装脚本会真的加载一次并调用 ledger_balance 做验证。
理财工具与收益降级链（B）¶
| 工具 | 作用 |
|---|---|
wealth_add_product / wealth_update_product |
录入或修改持仓（含份额、手动收益、归档等） |
wealth_list_products |
列出持仓（可选含已归档） |
wealth_record_profit |
手填某天收益（同日重记幂等覆盖） |
wealth_refresh_profit |
按降级链刷新收益，缺失的产品明确报缺失 |
wealth_summary |
理财月度汇总：本月/累计收益、来源、到期提醒 |
收益降级链按顺序尝试，每一步留在返回值的 attempts 里：
manual— 手填当日收益api— 基金：份额 × (今日单位净值 − 上一交易日单位净值)estimated— 仅有涨跌幅时用持仓金额估算，明确标注估算not_covered— 银行理财无免费源，直接不可用stale— 失败则沿用上次记录，标明「非实时」unavailable— 无历史值则如实报缺失，不落库、不编数字
任何情况下都不会用「年化收益率 ÷ 365」推算昨日收益；七日年化仅用于展示。银行理财不做登录态页面抓取。
报告与定时任务¶
finance_monthly_report：月末双节报告（记账 + 理财，中间分隔线，无合并总额）finance_run_daily_job/finance_run_month_end_job：手动触发定时任务（幂等）finance_setup_schedules/finance_schedule_status：注册或查看定时任务finance_alerts/finance_status：数据源告警与插件自检
默认定时（可在 profile 覆盖）：每日 0 20 * * *，月末 0 21 28-31 * *（配置项见下文）。
安装与启用¶
拿到 zip 或源码目录后，进入纯英文、无空格的路径，执行官方安装脚本：
cd dsh-ledger-wealth # 解压到纯英文、不带空格的路径
node scripts/install-into-dsh.mjs
脚本用 DSH 自带的 pnpm 装进 profile，注册工具并调用 ledger_balance 验证通过后写入 dsh.profile.bundles。装完需重启 DSH。不需要 dsh CLI、不需要 npm 账号、没有 Python 依赖（OCR 若用 rapidocr 需自行配置 Python 路径）。
其他方式（完整说明见仓库 docs/INSTALL.md）：
node scripts/install-into-dsh.mjs --pack # 自包含副本，源码目录可删
node scripts/install-into-dsh.mjs --remove # 卸载
dsh plugin --profile desktop add link:/绝对路径/dsh-ledger-wealth # 有 dsh 命令时的等价写法
注意：插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可证，确认 OCR、基金接口等行为符合你的环境策略。社区目录（如 skillhub）与 DeepSeek / 幻方无官方从属关系；市场一键安装依赖 awesome-dsh-plugin 收录，本仓库说明见 docs/PUBLISH.md。
配置¶
默认配置在插件包 cordis.patch.yml；覆盖请在 profile 自己的 cordis.patch.yml 里对同 id 增加 config（勿改包内文件，升级会被覆盖）：
- id: ledger-wealth
config:
timeZone: Asia/Shanghai
dbPath: '' # 空 = ~/.dsh/ledger-wealth/ledger.sqlite
dailyJobCron: '0 20 * * *'
monthlyJobCron: '0 21 28-31 * *'
fetchTimeoutMs: 8000
fundApiEnabled: true # 关掉 = 基金也走「沿用上次值」
bankApiEnabled: true # 银行理财目前没有免费源，恒 not_covered
ocrProvider: auto # auto | command | rapidocr | none
ocrCommand: '' # 自定义 OCR CLI，stdout 出文字
ocrVenvPython: '' # 装了 rapidocr_onnxruntime 的 python
数据位置与隐私¶
数据库默认路径：
~/.dsh/ledger-wealth/ledger.sqlite
记账表 ledger_entries；理财表 wealth_products、wealth_daily_profit；另有 meta、job_runs、monthly_reports、alerts 等运维表。备份即复制该 .sqlite；卸载插件不删数据，彻底清理需自行删除目录。
隐私相关：无遥测、无账号、无云端同步；网络请求主要为基金净值（东方财富公开接口），可在配置中关闭 fundApiEnabled。
开发与自检¶
维护者本地可跑：
cd dsh-ledger-wealth
node tests/run.mjs # 64 个用例，全内存库，不联网
node scripts/check.mjs # 语法 + 清单自检
表结构、工具签名与错误码见 docs/INTERFACES.md。
适用场景与小结¶
适合已在用 DSH、希望在本机会话里完成记账预览确认、持仓收益带来源标注、月末分节报告的智能体或开发者。不适合需要多设备云同步或把现金与持仓合成一个「总资产」数字的场景——插件刻意不做跨模块合计。
- 目录页：https://www.skillhub.cn/plugins/ainachoneko/dsh-ledger-wealth
- GitHub：https://github.com/ainachoneko/dsh-ledger-wealth
