dsh-finance-lab

DSH Finance

让 DeepSeek Harness 从“查一条行情”走向“看懂市场、管理组合、组织研究”。

English README · MIT License

DSH Finance 是一个面向 DeepSeek Harness 的金融插件：它把 A 股、港股、美股、基金、宏观数据和财经新闻接入模型，同时提供一个可停靠的本地金融面板。行情通过公开 HTTP 接口直连，持仓和自选股保存在本地 JSON 中，适合个人研究、组合复盘和多智能体协作。

个人投资首页（MVP）

新增建档 → 投资理由/验证指标/证伪条件 → 有来源的周复盘 → 用户复核流程。持仓导入和观点修改须到首页预览确认；面板任务先明确选择目标会话。收益按原币展示，缺汇率不合并。当前周复盘需主动触发，尚非后台自动调度。

面板导航现分为「我的工作台 / 市场研究 / 数据与设置」，首页采用概览、档案与判断、每周复盘、待确认四个分区。正确性回归可运行 npm run test:personal、npm run test:regressions 和 npm run test:offline；交付边界与验证说明见 个人首页说明。

安全变更： API默认仅本机访问。远程部署需认证代理、受保护的后端端口及 DSH_FINANCE_TRUSTED_ORIGIN 配置；不能将Origin检查当作登录鉴权。详见实现范围、指标定义与验收边界。以下旧功能说明中的直接写入和跨币种模拟，以此处新约束为准。

你可以用它做什么

• 跨市场看行情：A 股、港股、美股和公募基金的报价、K 线、列表与代码解析。
• 快：行情优先走本地 WeStock CLI——批量取（一次调用拿多只标的）、并行调用、结果缓存与陈旧复用、失败即熔断；HTTP 源保留串行间隔做回落。面板首屏从「逐只串行 + 死等超时」降到秒级。
• 从数据到判断：本地计算 MA、MACD、RSI、KDJ；查询财务指标、市场指数和行业板块。
• 跟踪市场叙事：读取中国 CPI/PPI/PMI/GDP/M2、市场电报、个股新闻，并通过 DuckDuckGo 免费搜索网页。
• 读券商研报：经 WeStock CLI（腾讯自选股，免鉴权）拉取个股研报列表与正文（机构、评级、时间）。
• 沉淀投研过程：研报、财报、资讯与个人观点统一进「投研资料库」，必带来源与时间、可关联标的与观点，支持持续收集、追加批注与归档。
• 资料与本地文件双向联动：正文是工作区里的 Markdown（<vault>/<年>/<id>-<slug>.md），目录被实时监听——在编辑器/文件工具里新建或改动文件会自动回灌索引，面板里改正文也会写回同一个文件。
• 对话 ↔ 面板打通：对话里收集/产出的资料自动落库并实时出现在「资料」页（顶部回执 + 标「对话」来源）；资料详情的「问 Agent」「让 Agent 整理」会把上下文拼成提问直接发进当前会话，Agent 再用 add_research_note / update_research 回写资料库，形成「对话收集 → 资料沉淀 → 面板维护 → 继续追问」闭环。
• 管理自己的组合：维护持仓和自选股，计算市值、盈亏、资产类型/市场分布，以及 top1、top3 和 HHI 集中度。
• 用研究团队拆解问题：内置行情、基本面、宏观、基金、消息和风险管理 playbook，可交给 DSH subagent 并行研究后汇总。

核心体验

一个面板，十二个视角

从侧边栏打开 📈 金融面板，可在以下标签页之间切换：

面板开关（panelOpen / panelDocked）是 volatile 配置：优先写回 profile；若当前 profile 不可写（本版本 configForms.set 会返回不可写），客户端自动退回 localStorage（dsh-finance:panelPrefs），并在面板顶部提示，保证面板打得开、刷新后状态保留。默认以浮层抽屉打开（dev_web.sh 生成 panelDocked: false；停靠页需要宿主 dock 容器，未选择工作区时可能不渲染），可在面板内一键切换为停靠。

持仓截图也可以交给 Agent 识别，再通过 import_holdings 批量写入本地文件；面板会自动刷新。点击持仓或自选中的股票/基金即可打开完整 AI 解读，首次主动点击后才生成，报告会缓存到本地并支持重新生成。插件只修改本地持仓数据，不执行真实交易。

面板与对话双向通道

面板与模型之间是双向实时的：

• 面板 → 对话：点击持仓/自选触发解读时，面板把任务注入当前 Harness 会话。
• 对话 → 面板：工具对持仓、自选、解读缓存、数据源策略、技能开关的修改，经服务端事件总线（GET api/events，SSE）即时推送到面板，无需等待轮询；模型还可以调用 panel_navigate 把面板切到指定标签页、聚焦某只股票的 K 线，或直接打开 AI 解读。
• 60 秒轮询保留为兜底；SSE 断线时 EventSource 自动重连。

What-if 再平衡模拟

simulate_rebalance 基于本地持仓做纯模拟推演，不修改持仓文件、不下单：

• trades 模式：给定买卖列表（先卖后买、现金约束、超卖自动截断）；
• targets 模式：给定目标权重（占「持仓市值 + 可用现金」的百分比），自动折算为交易；
• 输出前后对比：总市值、现金、权重、top1/top3、HHI、分币种敞口，以及全部警告与口径说明（按最新价成交、不计滑点费用、跨币种未折算汇率等）。

面向模型的金融工具

快速开始

1. 安装并构建

需要 Node.js ^22.19、>=24.2（dsh 的 bin 依赖 import.meta.main，24.0/24.1 会让 CLI 静默退出）：

cd dsh-finance-lab
npm install
npm run build

安装必须解析 peer 依赖：dsh 把服务定义包（dsh-jobs、dsh-attachment、dsh-session-persistence …）声明为实现包的 peer。仓库内 .npmrc 显式设置 legacy-peer-deps=false，否则本地安装不是完整的 dsh 运行时，profile 中每个条目都会 failed to import。

2. 先探测公开数据源

东财、腾讯、Yahoo 和 DuckDuckGo 都是公开源，可能受到网络波动、风控或限流影响。首次运行建议先探测，插件启动时会读取报告并优先使用健康的 provider：

npm run probe

# 指定输出和请求间隔
npx tsx scripts/probe_sources.ts \
  --out data/probe-report.json \
  --gap-sec 3

# 只探测某个 capability.provider
npx tsx scripts/probe_sources.ts --only kline.em_kline

报告默认写入 data/probe-report.json。全部公开源不可用时，行情工具会返回不可用信息；本地持仓 CRUD 仍然可以使用。

3. 接入 DeepSeek Harness

将当前项目目录注册到 web profile（dsh plugin 在 profile 目录里执行 pnpm；CLI 版本需与插件依赖一致，对本仓库即 0.2.0-rc.2）：

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin \
  --profile web add /absolute/path/to/dsh-finance-lab
npx @deepseek-ai/dsh@0.2.0-rc.2 web

dsh web 等价于 dsh --profile web；profile 由第一个位置参数选择，其余参数转发给应用。

本地开发也可以直接运行（scripts/dev_web.sh，多应用并行安全）：

bash scripts/dev_web.sh
# 可选环境变量：DSH_HOME（默认 <repo>/.dsh-home）、DSH_PORT（默认 0 = OS 分配）、
#               DSH_PROFILE（默认 web）、DSH_NODE、WESTOCK_BIN、LLM_BASE_URL/LLM_MODEL

该脚本按顺序保证隔离：① 每个应用独立 $DSH_HOME（profile/session/存储/数据互不干扰）→ ② 挑选支持 import.meta.main 的 Node（读 .nvmrc，挑不到直接报错而不是静默退出）→ ③ 端口默认 0 由 OS 分配（避免与其他插件应用抢端口）→ ④ 生成 $DSH_HOME/dsh-finance.overlay.yml（插件依赖、dataDir、数据源与 LLM provider 一律写在 profile 层，经 --patch 应用）→ ⑤ dsh plugin add 后启动。

WeStock CLI 未安装时，行情/财报/资讯会回落到 HTTP 源，仅研报不可用；安装（pinned + SHA256 校验）：

npm run westock:install        # → <repo>/.dsh-home/bin/westock，脚本自动识别

如果需要使用开发期的绝对路径 overlay（只挂载宿主半，不含面板客户端 bundle）：

npx @deepseek-ai/dsh@0.2.0-rc.2 web --patch ./cordis.dev.yml

注册插件后，从 Harness 左下角的 📈 金融面板 打开 UI；模型工具会自动出现在工具列表中。

配置与数据

默认配置位于 cordis.patch.yml：

dataDir 的相对路径以插件包目录为基准。同一份源码被注册进多个 dsh profile 时，请在 profile 层把 dataDir 指到各自的目录（或给 portfolioPath / probeReportPath 绝对路径），否则几个 profile 会共用同一份数据。这些文件属于本地运行数据，不会被提交。

panelOpen / panelDocked 在 Config schema 中声明为 volatile：dsh 0.2.0 的配置面板只暴露 volatile 字段，并把它们的值写到 profile 用户层（$DSH_HOME/profiles/<name>/cordis.patch.yml）。面板开关按钮经 ctx.configForms 读写该条目，因此重启后开关状态仍然保留；其余字段属于组合配置，改动后由 Loader 重新应用条目。

可用性测试

测试分两层：功能正确性（离线、可重复，必须全绿）与数据源可用性（真实网络，允许失败但标注原因）。

npm run build
npm run test:offline    # 离线功能正确性：解析/映射/持久化/校验/日志/registry/能力目录/K线数学/请求校验
npm run test:quant      # 量化金样本：确定性回测/稳健性/搜索/策略库/分币种采样（手工推演基准）
npm run test:personal   # 个人工作台：档案、观点版本、每周证据任务
npm run test:regressions # 跨模块回归（总线/确认/历史/分析引用契约等）
npm run test:ui         # UI 冒烟（真实浏览器）：无浏览器/无 DSH_UI_URL 时诚实 SKIPPED
npm run test:westock    # WeStock 可用性（真实网络）：精选用例 + 能力全量扫描
npm run test:avail      # 全量数据源 + 资料库真实收集

# 只测试某个分组
npm run test:avail -- --group westock
# 可选分组：ashare、hk、us、tools、westock、search

详细结果与已知限制见 docs/self-test-report.md；优化方向见 docs/analysis-report.md。

数据源与边界

• 运行时不依赖 Python akshare；接口形状参考 AkShare 源码，并在 src/data/providers.ts 中保留来源注释。
• A 股、港股、基金、宏观和新闻主要使用东方财富，部分行情使用腾讯；美股优先使用 Yahoo Finance，并以东方财富兜底；网页搜索使用 DuckDuckGo。
• WeStock（腾讯自选股 CLI，免鉴权）提供 A/港/美行情与 K 线、券商研报和公司简况，默认优先级高于东财；CLI 未安装时自动回落到 HTTP 源。
• 除上述能力外，WeStock 另接入 55 个能力（资金流、两融、龙虎榜、北向/南向、卖空、股东、分红、回购、一致预期、评级、评分、ESG、公告、事件、风险、停复牌、ETF、宏观、指数/板块、产业链、智能选股、期货、外汇、可转债…），见「WeStock 扩展能力」。
• provider 会按 capability 独立降级。公开源并不承诺稳定性或完整覆盖，返回结果应结合时间、市场状态和来源健康度解读。
• 本项目用于研究和组合记录，不构成投资建议；不连接券商，也不执行下单。

多来源数据（MCP）

除公开免费源外，可通过 mcpSources 接入需要凭证的外部数据源，其工具会被桥接进模型工具集，并显示在金融面板「接口」标签页。支持三类：

默认预置两个（需自备 token）：

• 妙想数据（mx，mcp-http，东方财富）：A股/港股/美股/基金/债券/指数板块/宏观/新闻/公告的自然语言查询。
• 盈米（yingmi，cli）：基金详情、风险与资产配置等能力，依赖全局安装的 yingmi-skill-cli。

Token 解析优先级：环境变量（apiKeyEnv，如 EM_API_KEY）→ 本地 data/mcp-secrets.json（不提交，见 data/mcp-secrets.example.json）→ 配置内联 apiKey。也可在面板「接口」页点 🔑 直接填写 token：写入 data/mcp-secrets.json 并即时热重载（断开旧连接、重新桥接工具，无需重启）。

WeStock 扩展能力（腾讯自选股 CLI）

CLI 自带 40+ 子命令。为避免"插件设计把数据源用窄了"，这里用表驱动的 capability 目录 （src/data/westock-capabilities.ts）成建制接入，再加一个通用 CLI 桥兜底：

• 新增一个能力 = 加一行 spec：registry 目录、面板数据源页、能力目录、HTTP 路由、测试扫描全部自动生效。
• 不受目录限制：westock_call 可直接执行任意只读 CLI 参数（如 ["fund","flow","sh600519"]）， 白名单拒绝 update/upgrade/config/login 等写操作与 shell 元字符。
• 可用性：npm run test:westock 会遍历整个目录真实调用（55 项），输出分组通过率与失败原因。
• 面板：「发现」页展示涨跌分布、热搜股票/板块、机构龙虎榜。

典型投研链路：screen_stocks 初筛 → get_realtime_quote/get_stock_kline → get_consensus/get_financial_indicators → get_money_flow/get_north_holding → collect_research 沉淀研报 → add_research_note 记录观点。

数据源选择（多来源策略）

面板「数据源」页可按 capability 选择使用哪些 provider（quote/kline/hk_*/us_*/web_search 等常有多个来源共存）：多选、点击顺序即调用优先级，绿点=探测可用。选择保存到本地 data/provider-policy.json 并即时生效（用户选择优先于探测顺序）。妙想/盈米作为整体数据源在「接口」页开关。

本地历史库与 K 线事件

面板「K线」页可把日 K 线与事件落地到本地库并追加更新（data/history/<code>.json）：

• sync_history（工具）/ POST api/history/sync：抓取日 K 线（A股/港股/美股/基金）并按日期去重合并，股票同时把财报日期存为事件。
• add_market_event / get_history / list_history：追加分红/公告等自定义事件、读取、列出。
• K 线图上以虚线标注事件（财报=蓝、分红=绿），下方列出事件时间。

技能管理

面板「技能」页统一管理技能（类似工具）：本插件 playbook 技能可启用/停用（进入系统提示）；盈米的 11 个金融场景 skill（标准 SKILL.md）可勾选可见范围，写入 remote-skill scope。选择保存到 data/skills-policy.json。

项目结构

src/                  插件服务、provider、模型工具和金融面板
src/panel-bus.ts      面板 ↔ 对话双向通道的事件总线（SSE 推送）
src/rebalance.ts      What-if 再平衡模拟引擎（纯函数，不改持仓）
src/mcp/              外部 MCP 数据源桥接（妙想 HTTP / 盈米 CLI）+ token 热重载
src/history/          本地历史库（K线/财报/分红）与同步
src/log.ts            结构化日志（JSONL，级别可配，替代原先静默的 catch）
src/data/westock.ts   WeStock CLI 数据源（Markdown 表格解析、symbol 映射、研报、通用 CLI 桥）
src/data/westock-capabilities.ts  WeStock 能力目录（表驱动）+ provider 工厂
src/tools/westock.ts  WeStock 工具集（资金/股东/研究/事件/选股 + westock_call 通用调用）
src/research/         投研资料库（Markdown 落盘 + 索引 + 收集/观点/归档）
skills/               财务分析、组合、策略、风控与研究团队 playbook
scripts/              provider 探测、可用性测试和本地 Web 启动脚本
cordis.patch.yml      Harness 插件注册与默认配置

命令行方式使用 WeStock

插件内部就是「spawn westock 二进制 + 解析 Markdown 表格」，因此可以直接在终端/Agent bash 里敲：

./scripts/westock.sh quote sh600519              # 透传原生子命令（输出 CLI 原文）
./scripts/westock.sh kline sh600519 --period day --limit 10
./scripts/westock.sh fund flow sh600519 --json   # 表格解析成 JSON
./scripts/westock.sh --cap consensus --args '{"code":"600519"}'   # 走能力目录：缓存 + 多源回落 + JSON
./scripts/westock.sh --list --group 研究          # 能力目录
./scripts/westock.sh --status                     # 二进制与版本
npm run westock -- quote sh600519                 # 等价写法

• 二进制定位：--bin / WESTOCK_BIN / <包>/.dsh-home/bin/westock / ~/.westock/bin/westock；未安装时提示 npm run westock:install。
• 超时用 WESTOCK_TIMEOUT_MS 控制（默认 20000）。
• Agent 侧不需要 shell：用工具 westock_call（传 argv 或 capability+args）即可，同样是只读白名单。