mzzsfy/dsh-plugin#dsh-stock-assistant

DSH 全局股票工具。左侧“股票”入口打开独立主页面，无会话也可使用。切换、关闭 DSH 会话或临时打开其他工具，不会清除股票工具的搜索、详情、排序、滚动位置和设置草稿。

支持八个市场（沪/深 A 股、港股、美股 NYSE/NASDAQ、日经、韩证、伦敦）：自选（置顶、分组、组内涨跌统计与折叠、拖拽排序、别名、删除撤销）、名称/代码/拼音首字母搜索（多市场候选带币种徽标）、行情与 K 线图表（分时/日K/周K/月K，MA/EMA/BOLL/BBI 可分别开关、成交量副图、昨收/价格标记/区间高低参考线，lightweight-charts 渲染）、价格标记（成本/卖价，单只最多 12 条，等权成本均价与浮盈/潜在收益）、悬浮盯盘（列表与图形双模式、只盯勾选的标的、可拖动、常驻在所有面板之上）、基础详情、涨跌排序、手动刷新、暂停采集，以及数据源与能力路由设置（含"应用推荐配置"与按市场配置 K 线）。不做交易、持仓管理或资讯；价格提醒仅限自选标记价穿越，经页内/系统通知或已安装的通知插件呈现。

数据结构与持久化

不使用 DSH 默认设置系统。 本插件不声明 Config，不调用 settings 或 configEditor。配置界面位于股票工具自己的“设置”视图中。

通过宿主 storageDomain 使用专用 stock_assistant 数据域（2026-10-30 前为 stock_sidebar，随包改名一并更名；生产 profile 未挂载过旧域，无迁移），version=1、layout=single：

表 / 记录	内容
control/root	自选证券、手动顺序、置顶、别名、显示偏好、Provider 实例、能力路由、控制版本、近期幂等操作结果
cache/catalog:<instance>:<market>	可重建的标准证券目录、完整性、来源和获取时间
cache/calendar:<instance>:<market>	可重建的交易日历、日期范围和来源

具体介质路径由宿主的 storage backend 决定。本插件不向会话存储写数据。报价仅保留在 Host 内存中；搜索、详情、设置草稿等浏览状态由每个浏览器页面的运行时持有，刷新浏览器会重建这些临时状态。

浏览器本地另存两项显示偏好，不进 control/root：悬浮盯盘的开关/位置/勾选目标（ssb-floating）与 K 线辅助线开关（ssb-guides）。这两项都是纯客户端显示状态，跟着屏幕与个人习惯走，多设备之间没有同步价值；放进宿主 preferences 的话，每加一个开关都要改协议 schema 并重启宿主才能生效，收益不成比例。代价是它们不随账号同步、清空站点数据会丢。刷新间隔与涨跌配色仍留在宿主侧，因为那两项影响上游请求节奏与全局显示语义。业务数据（自选、成本、别名、分组、数据源与路由）一律只走宿主存储。

写操作在单一队列中执行，并携带版本及操作 ID。持久化成功后才发布；版本冲突保留用户输入并要求重新确认，写盘失败保留原数据。删除撤销有效期为8秒，恢复到当前列表原邻居附近，不回滚别页修改。损坏的权威记录会阻止激活，不会静默清空自选。

初次使用

全新安装即内置默认数据源：东财、新浪、腾讯、雪球四个免凭据公开源（东财主源，新浪/腾讯/雪球按市场做报价或 K 线备用；保守预算 60 次/分起步），八个市场的目录、搜索、报价、K 线共 32 条能力路由全部配好，无需任何注册。打开后即可「检查所有来源能力」→ 保存 → 同步目录 → 用「浏览市场」翻页浏览全市场证券并直接加自选，或按代码/中文名/拼音首字母搜索。日经、韩证、伦敦三个市场由东财全球搜索与目录页覆盖，其成交额字段来源恒给 0，界面按缺失呈现而不是显示「0」。

• 顶栏「浏览市场」提供无目的浏览：按市场分页查看全部 A 股，行内一键加自选；目录未同步时页内有同步引导。
• 搜索在目录未就绪时不再死路：错误提示带「前往浏览市场」直达入口。
• 设置页在配置被清空时提供「启用默认数据源」一键恢复（与初始安装同一配置来源）。

需要目录/日历（搜索、日历休市调度）或更正式的数据合同（权限表、配额文档、服务协议）时走 Tushare：

1. 当前 main 的凭据优先由宿主凭据服务托管：在“股票 → 设置 → 数据源”实例卡的密钥输入框直接录入（写入宿主凭据存储，不回显、不落插件配置）；服务接口不全时回退 启动 DSH 的 Host 进程环境变量 DSH_STOCK_TUSHARE_TOKEN（或同层 .env）。0.4.0 发布版没有凭据服务，只读该环境变量。插件只保存引用名/变量名与数据路由；修改引用名不会迁移已有密钥。
2. 打开“股票 → 设置”，添加数据源实例，填写账号实际允许的请求预算。同一账号的实例使用同一“共享额度组”。新实例额度默认为未知；未填写时只允许每组最多每10秒一次主动探针，实际目录同步与报价采集均禁用，不假设任何免费套餐额度。
3. 为上海/深圳分别选择证券目录、报价、交易日历来源。可以只启用自己需要的市场和能力。
4. 点击“检查所有来源能力”。所有被引用能力检查就绪后保存。检查消耗该来源请求额度，检查通过不代表任何第三方展示许可。
5. 同步需要的市场目录和日历，搜索证券、选择候选并确认添加。
6. 列表或详情可见时自动采集；进入设置、搜索、隐藏页面或暂停时停止自动采集。暂停期间手动刷新可更新当前静态快照。

设置页按「① 数据源 → ② 市场与能力 → ③ 显示偏好」递进组织；每个数据源实例卡内可见适配器一句话说明、「接口反代」端点覆盖（自建反向代理/镜像时替换地址，留空用官方默认；东财五个端点、腾讯两个端点）、高级预算折叠组与「运行状态」最近请求轨迹（环形 20 条：时间/能力/状态/耗时，用于确认上游是否可达）。实例还支持可选 HTTP 代理出口（http(s)://[user:pass@]host:port，经 undici ProxyAgent；一般无需配置）。列表页顶部常驻数据源概览横幅：启用数/最近请求失败实例一目了然，「管理」直达设置。

Tushare 的 rt_k、stock_basic、trade_cal 权限分别由账号决定。目录与日历权限不足不等于“市场为空”。rt_k 使用 HTTPS；本插件不使用 HTTP 降级，也不通过浏览器直接访问来源。具体能力检查以实际账号结果为准。

数据源适配器

生产内置六个适配器，各自独立文件（src/providers/），互不依赖：

适配器	能力	凭据	边界
tushare	quotes / catalog / calendar	宿主凭据服务或环境变量（默认引用 DSH_STOCK_TUSHARE_TOKEN）	唯一有正式权限表、配额文档与服务协议的渠道；三种能力可分开路由
finnhub	quotes	宿主凭据服务或环境变量（默认引用 DSH_STOCK_FINNHUB_TOKEN）	美股 XNAS/XNYS 实时报价；免费档不含 K 线，单只一请求，不适合持续轮询
tencent	quotes / kline	免凭据	公开网页接口；非官方、无 SLA，协议随时可能变化
sina	quotes / catalog	免凭据	同上；价格恒三位小数，适配器裁剪到分；目录仅沪深
eastmoney	quotes / catalog / search / kline	免凭据	同上；目录分页抓全量（单市场约2500只，页频受限流退避约束），联想搜索支持中文/代码/首字母拼音；K 线含分时与日/周/月，分时时间戳统一按北京时间解析
xueqiu	quotes	免凭据（匿名 token）	同上；可混装多市场，额外提供换手率与市值

零注册全流程：只添加 eastmoney 实例（设置页选适配器即标"免凭据"，默认保守预算 60 次/分），八个市场各配 catalog/search/quotes/kline 四条路由，检查→保存→同步目录→搜索添加→看行情，全程不需要任何账户。日历能力仅 Tushare 提供；缺日历时插件按"未知交易状态"保守采集，功能不受阻。

混合路由：可把沪深行情分别路由到不同来源（沪市腾讯、深市东财、新浪备用等），目录/搜索用东财、日历用 Tushare——全部在设置页按市场/能力勾选。同一报价的现价、昨收、涨跌和时间始终来自同一适配器，不混拼字段。

免凭据机制：实例 credentialRef=null 时跳过凭据解析（宿主凭据服务或进程环境变量），但 schema 强制其声明保守预算（防无界请求）；凭据型适配器切换回档时自动恢复引用名输入框。

新增平台步骤：在 src/providers/ 实现标准合同（descriptor.credential 声明 'none' 或默认引用名 + 能力方法 + probe），在 application.mjs 的 registry 登记，测试放 test/public-providers.test.mjs 或 test/<adapter>.test.mjs。UI、存储、自选模型零改动。

报价路由可选一个备用源，自动切换默认关闭。开启后，连续三轮完全由 NETWORK/TIMEOUT 失败才整条路由切换；权限错误、额度限制与逐证券缺失不触发。切换增加运行代次并丢弃旧请求，最短驻留10分钟，回主源必须手动检查。设置视图显示当前备用选择与回主源操作。

调度与接口

同额度组顺序执行，上游启动间隔至少1秒；最多两个额度组并发。总账号、能力子额度、每日额度和证券计费额度共同约束请求。网络错误指数退避；429遵守 Retry-After；AUTH/PERMISSION/BAD_PAYLOAD暂停该能力，检查或修改后恢复。已知休市/午休不持续采集，日历缺失按未知状态保守采集。

HTTP 路径前缀 /api/stock-assistant：snapshot/search/watchlist/preferences/provider-check/configuration/catalog-sync/route-selection/refresh。写接口均为POST，读接口GET。普通请求上限10秒、单次上游8秒；目录同步30秒，多能力检查最多60秒。刷新直接等待批次并回快照，同价也有获取时间回执。周期启动下界同时考虑用户周期与来源额度。

通知复用 @mzzsfy/dsh-common-tools 的页面共享 WS，不创建股票专用 socket。失效通知与快照拉取分别合并；快照单飞、至少1秒启动间隔，失败不自循环重试。页面需求通过同一总线续租，不以 HTTP 心跳维持。

安装与开发

已发布 npm（当前 0.4.0），安装与升级走正式包：

dsh plugin --profile web add @mzzsfy/dsh-stock-assistant

随后重启该 profile 的宿主。仓库 README 对应 main（可能含尚未发版的改动），npm 页面上的说明是发版时的快照。仓库开发挂载遵循根目录 scripts/dev-link.mjs dsh-stock-assistant（工作副本 junction），装载层变更不走热重载，同样需要重启宿主。

要求 Node>=22，宿主已有 webServer（包括upgrade）、storageDomain 与有效 backend。0.4.0 发布版只读 Host 进程环境变量、不注入 credentials；当前 main 已把它列入注入服务，由宿主凭据服务托管，接口不全时回退环境变量。client 需要 slots/locale/layout。缺必需服务干净禁用。公共 client 依赖由 dsh-session-manager 的唯一占位项承载，本包只声明 dependency/external，不插第二条占位。Host/client使用同代 common-tools 0.3.x。

npm install --omit=peer
npm test

生产 client 是原生 ModuleLoader 单入口，没有生产打包步骤、独立状态库或 React 副本。devDependencies 的 React/ReactDOM/esbuild 仅用于实际组件测试和隔离验收夹具，不进入生产运行路径。

有头浏览器夹具可运行 node test/browser-fixture.mjs，输出随机本地端口。它使用固定行情、内存存储、真实client组件和真实公共快照调度器，测试传输替为夹具事件桥；不能将其作为真实Tushare账户或宿主WS验收证据。使用后终止该进程。

DSH 版本兼容

版本	状态	证据边界
0.2.2-rc.1	compatible	2026-11-09 隔离真宿主：导航入口、自选/搜索/浏览市场/详情/K线/悬浮盯盘/设置、真实东财行情与八市场路由；截图资产同源采集
0.2.1-rc.5	compatible	manifest 登记；仅有 .compat/0.2.1-rc.5 的 crash-only 装载记录（page true），未做功能复测
0.2.1-rc.2 / 0.2.1-rc.3	compatible	早期隔离验证：导航入口、main 页面、样式、快照路由、WS ready→invalidate、重载后偏好保留；rc.3 另验证无凭据 AUTH 检查拒绝与保存守卫
其余版本	unknown	未实测不声明

逐项证据和局限见兼容性测试，变更记录见CHANGELOG。界面截图（2026-11-09 隔离宿主实采）见assets/screenshots/dsh-stock-assistant。实现规格与研究分别见开发文档、调研文档。