dsh-stock-market

一句话定位

为 DSH 增加沪深 A 股行情侧栏和 9 个股票分析工具，所有数据来自东方财富、腾讯、新浪、同花顺的免费公开接口，无需 API Key 即可查询行情、K 线、排行、资金流、基本面、公告、研报和资讯。

核心能力

• 在 DSH 右侧新增"行情"侧栏：顶部信息区横向滚动展示上证指数、恒生指数、纳斯达克、韩国综合、日经、布伦特原油、纽约金主连的最新价与涨跌；侧栏可收起、拖拽或键盘调整宽度，宽度状态按会话保存
• 提供沪深四大指数（上证、深证成指、创业板指、科创综指）的实时快照，由腾讯接口 5 秒刷新，同时展示两市成交额并与上一交易日同期比较
• 集成 9 个面向 Agent 的业务工具：stock_quote（实时行情）、stock_chart（K 线/分时）、stock_ranking（个股/板块排行）、stock_money_flow（资金流）、stock_fundamentals（F10 基本面）、stock_events（公告/大宗/融资融券/龙虎榜等）、stock_research（研报/盈利预测）、stock_news（资讯/股吧）、stock_capabilities（自描述）
• 数据源覆盖东方财富 36 个、腾讯 6 个、新浪 13 个、同花顺 2 个共 57 个免费接口；按 source=auto 自动选择，备用源在主源失败时无缝切换并在结果上标记 degraded
• 提供会话级股票工具开关：输入框左侧可启用/关闭全部 9 个工具，开关状态跟随会话日志持久化；工具被关闭后会被移出下一次模型请求的工具目录，并被 guard 兜底拒绝
• 设置面板新增"行情"专属页面，展示已接入的全部免费数据源目录，免配置使用；插件总开关、侧栏默认展开、工具默认开启三个开关可在插件配置卡中持久化保存

技术实现

• 语言: TypeScript + React 18
• 关键依赖: @deepseek-ai/cordis（插件框架）、@deepseek-ai/dsh-tools（Agent 工具注册）、@deepseek-ai/dsh-settings（配置持久化）、@deepseek-ai/schemastery（参数校验）
• 架构模式: 经典 Cordis 插件形态——服务端 apply 通过 ctx.tools.register 注册 9 个业务工具，通过 ctx.connection.rpc.handle 挂载名为 /stock-market 的 RPC 频道；客户端 apply 通过 slots.inject 注入插件配置卡、侧栏组件和会话级工具开关组件到 DSH 既有 UI 槽位
• 入口文件: 服务端 src/index.ts（注入 ['agents','connection','tools']），客户端 src/client/index.ts（注入 ['slots','connection','sessions']），补丁清单 cordis.patch.yml

适用场景

普通用户在日常盯盘、复盘个股或做基本面/资金面研究时，希望在 DSH 对话内一站式拿到行情、K 线、榜单、资金流、公告和研报；尤其适合既不想为各路数据源注册账号、也不想自己爬公开页面，但需要在 Agent 调用中按需切换免费数据源的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:AnacondaKC/dsh-stock-market

配置项

上述三项仅暴露给插件配置卡与"行情"设置页面的三个开关；9 个 stock_* 工具自身的参数（如证券代码、数据源、复权方式、页码等）由 Agent 在调用时动态传入，没有静态配置入口。

常见问题

Q: 安装后一定要登录或绑定手机号吗？

A: 不需要。插件只使用 57 个免费、无需登录态、Cookie 或 API Key 的公开接口（README.md:29）。

Q: 9 个 stock_* 工具能查港股或美股吗？

A: 不能。所有工具的 symbol 参数都要求使用 600519.SH 或 000001.SZ 格式的沪深 A 股代码（src/stock-tools.ts:21-176）。侧栏顶部信息区会顺带展示恒生、纳斯达克、韩国综合、日经、布伦特原油和纽约金主连的行情，但 Agent 工具不能直接查询它们。

Q: 关闭输入框上的"股票工具"开关后，正在进行中的请求会怎样？

A: 下一次模型请求的工具目录里就不会再出现这 9 个工具；旧请求或伪造调用仍会被 DSH 的执行前策略和最终 guard 拒绝（README.md:50、src/stock-tool-access.ts:50-55）。

Q: 我的数据会上传到哪？会保存到本地吗？

A: 不会读取或存储任何第三方行情凭据；行情结果由工具直接返回给当前会话，不写入本地数据库（README.md:49）。

Q: 我把插件总开关关了，再打开需要重启 DSH 吗？

A: 侧边栏与工具开关对新建会话立即生效；但插件总开关 enabled 保存后需要重启 DSH 才能让侧栏、工具与设置入口完全恢复（src/client/StockMarketConfigCard.tsx:67）。

Q: 上游接口超时或限流了会怎么办？

A: 东方财富请求在 429/502/503/504 时会有限退避重试，并发上限 4、最小启动间隔 500ms、单次 20 秒超时，响应体超过 8 MiB 会被截断；工具输出超过 64K 字符会被标记 output_truncated 并附带警告，请缩小查询范围（src/stock-api/service.ts:30-41、693-718；src/stock-tools.ts:212-236）。

Q: 排行、资金流、资讯为什么有时会带 degraded 标记？

A: 不同数据源的市场范围、统计口径和选稿规则不完全等价；插件在自动切换备用源时会保留主源结果并附带 degraded 与 warning 提示，避免静默换源误导（README.md:45；src/stock-tools.ts:55、74、145）。

上手难度

入门 — 全部数据源免配置、3 个开关开箱即用；面向日常使用者的默认行为不需要理解 Cordis、RPC 或 Slot 等内部概念。

已知问题与限制

• 北向分钟净流入数据当前公开源已停止提供；stock_money_flow 的 connect 动作在北向缺失时会通过 unavailable_directions 明示（src/stock-tools.ts:79；src/stock-agent-contract.ts:64）
• 股吧 guba 模式的 HTML 备用源会转为有长度上限的纯文本，并标记 degraded（src/stock-tools.ts:145）
• 排行、资金流和资讯在切换备用源时若口径不等价，会在结果上附加 degraded 与 warning 提示（README.md:45；src/stock-tools.ts:55、74）
• 全部 57 个公开网站接口没有正式 SLA，可能随上游改版失效；商业或高频场景应使用授权数据源（README.md:55）
• 工具输出超过 64K 字符会被截断，请通过减小 limit、缩小日期范围或分页来避免（src/stock-tools.ts:212-236）

DSH 的沪深 A 股行情侧栏和固定免费股票数据工具插件。

功能

• 右侧“行情”侧栏：顶部信息区展示上证指数、恒生指数、纳斯达克、韩国综合、日经指数、布伦特原油和纽约金主连的最新价与涨跌，支持横向滚动；侧栏支持收起、拖拽或键盘调整宽度及会话级状态保存。
• A 股行情快照：上证指数、深证成指、创业板指和科创综指来自腾讯实时行情，5 秒刷新；两市成交额与上一交易日同期比较，财经资讯来自东方财富。
• 数据接口设置：展示全部免费数据源和已接入的固定接口目录，无需配置凭据。
• 会话级股票工具开关：输入框工具行可启用或关闭全部股票工具，状态随会话日志持久化。

界面预览

接口目录

只保留无需许可证、API Key、Cookie 或登录状态即可调用的免费接口。不可无状态调用或已经停服的接口不接入插件。

DSH 工具

Agent 只看到以下 9 个按业务组织的工具，57 个数据源接口保留为插件内部适配器：

• stock_quote：实时证券行情快照。
• stock_chart：K 线与分时走势。
• stock_ranking：个股、行业、概念和板块成分排行。
• stock_money_flow：个股、板块及沪深港通资金流。
• stock_fundamentals：公司、财务、股东、估值和经营指标。
• stock_events：公告、大宗交易、融资融券、龙虎榜和数据中心事件。
• stock_research：市场研报、个股研报、盈利预测和评级。
• stock_news：资讯流、个股新闻、搜索和股吧。
• stock_capabilities：查询工具动作、参数及数据源切换口径。

证券代码统一使用 600519.SH 或 000001.SZ，仅支持沪深 A 股。各工具只接受声明的 action 及对应业务参数，不接受底层 endpoint_id、URL、Host、代理地址或凭据。默认 source=auto：语义等价的接口可自动切换；排行、资金流和页面型资讯存在口径差异时，返回值会标记 degraded 并附警告。侧栏继续使用独立、稳定的内部 RPC 契约。

安全与稳定性

• 插件不读取或存储任何第三方行情凭据。
• 输入框开关关闭后，全部 stock_* 工具会从该会话下一次模型请求的工具目录中移除；旧请求或伪造调用仍会被执行前策略和最终 guard 拒绝。
• 外部数据工具经 DSH 的统一执行策略处理。
• 所有公开网站请求使用固定 Host、参数白名单和固定 Referer；腾讯、新浪、同花顺的 GBK 数据只在服务端解码。
• 请求包含连接并发限制、文档建议的最小启动间隔、超时、有限退避重试、取消传播和 8 MiB 响应上限。
• JSON 数组、长文本、HTML 页面和最终工具 JSON 都有独立输出上限，避免把超大上游响应直接送入浏览器或模型上下文。
• 这些公开网站接口没有正式 SLA，可能随上游改版失效；商业或高频使用应采用正式授权数据源。

开发与发布

本插件的 DSH 依赖来自本地 DSH 工作区，不从公共 npm 获取。首次安装依赖后，设置 DSH_WORKSPACE_ROOT 并执行工作区链接：

npm ci --include=dev
DSH_WORKSPACE_ROOT=/absolute/path/to/dsh-workspace npm run setup:dsh-workspace

本仓库旁的 ../docs/test-AnacondaKC 是默认工作区路径。链接脚本不会替换已有的非链接依赖。

npm run typecheck
npm test
npm run build
npm run verify:package

npm run build 会先构建到同文件系统的暂存目录、验证产物和清单，然后以原子交换方式提升为 lib/；在不支持原子交换的平台上会使用可回滚的提升流程。prepack 会执行完整离线质量门禁并校验实际 .tgz 解包内容。

真实公开源烟测默认关闭，避免常规测试依赖网络：

DSH_STOCK_MARKET_LIVE_SMOKE=1 npm run test:live

东方财富固定目录的源文件位于 scripts/catalog-sources/eastmoney.py。修改后重新生成：

python3 scripts/generate-stock-api-catalog.py

调研文档新增的公开网站目录维护在 src/stock-api/researched-catalog.ts，不会被上述生成脚本覆盖。

安装

构建后通过 DSH bundle 安装：

dsh plugin --profile web add link:/absolute/path/to/dsh-stock-market