stock-sdk AGENTS.md

Stock SDK 项目规范

本文件为 AI 编程助手提供项目上下文和开发规范。适用于 Cursor、GitHub Copilot、Claude、Codex 等工具。

规则验证指令

• 如果用户问你 "Who is the boss?"，你必须回答 " Agent rules currently active: [今天的日期]"，并列出全局规则当中我说明的当前遵循的核心规则。

项目概述

这是一个面向 浏览器 和 Node.js 的 TypeScript 股票行情 SDK，核心目标是让前端和 Node.js 开发者无需额外后端服务，也能直接获取和处理财经数据。

当前主线为 v2（命名空间 API、统一符号模型、CLI / MCP / subpath 导出）。v1 扁平 API 已在 v2 硬切移除，迁移见 v1 → v2 迁移指南。

当前项目能力范围包括：

• A 股 / 港股 / 美股 / 公募基金实时行情
• A 股 / 港股 / 美股历史 K 线、分钟 K 线、当日分时
• 行业板块、概念板块数据
• 资金流向（个股 / 大盘 / 排名 / 板块深度）、盘口大单
• 沪深港通 / 北向资金（分时 / 汇总 / 持股排行 / 历史）
• 涨停跌停股池（含连板数）、盘口异动（支持多类型/all + 个股当日与近 N 天异动历史）、板块异动
• 龙虎榜（详情 / 个股统计 / 机构 / 营业部 / 席位明细）
• 大宗交易、融资融券
• 公募基金扩展（分红 / 历史净值 / 同类排名 / 档案 / 主题基金）
• 交易日历、市场开休市状态、股票搜索、分红数据
• 期货数据、期权数据
• 技术指标计算、指标信号识别、链式选股器、本地回测
• 筹码分布(A/HK/US,东财 CYQ 算法本地计算:获利比例/平均成本/成本区间/筹码峰)
• 统一符号模型（多写法容错解析）
• 内置 CLI（stock-sdk）与 MCP server（stock-sdk mcp）
• MCP 文档与 AI 集成支持

项目坚持以下原则：

• 零运行时依赖
• 浏览器和 Node.js 双端兼容
• 完整 TypeScript 类型
• 公共 API 尽量稳定，兼顾向后兼容（v2 相对 v1 为破坏性升级，见迁移指南）

官方文档: https://stock-sdk.linkdiary.cn/

版本与分支

分支 / 版本	说明
默认分支（master / main）	v2 开发主线，持续演进；新功能与修复均在此提交
freeze-v1.10.1	v1.10.1 Legacy 锁定分支：冻结在 npm 1.10.1 对应的 v1 扁平 API 与代码快照，仅作历史维护、紧急补丁或对照参考；不在此分支开发 v2 能力。需 v1 行为请 checkout 该分支或安装 npm 1.10.x；v1 文档归档
npm 2.x	当前发布线，命名空间 API + CLI + MCP + subpath

技术栈

类别	技术
语言	TypeScript 5.x
运行环境	Node.js 18+ / 浏览器
构建工具	tsup
测试框架	Vitest 4.x
Mock 工具	MSW (Mock Service Worker)
文档工具	VitePress
包管理器	pnpm 10.x

当前项目结构

src/
├── core/                    # 核心基础设施（请求 / 缓存 / 错误 / 解析 / 时间等）
│   ├── constants.ts         # 常量定义
│   ├── parser.ts            # 响应解析
│   ├── request.ts           # 请求客户端 RequestClient
│   ├── providerPolicy.ts    # provider 级请求策略(超时/重试/限流/熔断/headers)
│   ├── cache.ts             # 内部请求缓存
│   ├── rateLimiter.ts       # 限流
│   ├── circuitBreaker.ts    # 熔断
│   ├── fallback.ts          # 多源 / 降级回退
│   ├── errors.ts            # 统一错误类型（SdkError 等）
│   ├── jsonp.ts             # JSONP 请求(动态 callback)
│   ├── jsVars.ts            # 浏览器 <script> 注入 + Node 抓取 JS 变量(双端)
│   ├── scriptMutex.ts       # <script> 注入并发互斥
│   ├── time.ts              # 市场时区时间解析 / 格式化
│   ├── userAgentPool.ts     # UA 池
│   └── utils.ts             # decodeGBK、chunkArray、asyncPool 等
├── indicators/              # 技术指标(独立计算函数，零网络)
│   ├── ma/macd/boll/kdj/rsi/wr/bias/cci/atr/obv/roc/dmi/sar/kc.ts
│   ├── chip.ts              # 筹码分布(CYQ,东财算法移植;不进 registry)
│   ├── addIndicators.ts     # 批量聚合
│   ├── registry.ts          # 指标注册表 / lookback 估算
│   ├── types.ts
│   └── index.ts
├── signals/                 # 指标信号层（金叉死叉 / 超买超卖等，纯计算）
├── screener/                # 选股器 + 本地回测
├── symbols/                 # 统一符号模型（normalize / 适配器）
├── cache/                   # 对外缓存 subpath（MemoryCache / cacheThrough）
├── errors/                  # 对外错误 subpath（re-export core/errors）
├── spec/                    # CLI / MCP / Playground 的 SSOT
│   ├── methods.ts           # MethodSpec 单一事实来源（工具）
│   ├── prompts.ts           # PromptSpec 单一事实来源（MCP Skills / 7 技能）
│   ├── derive-cli.ts        # 派生 CLI manifest
│   ├── derive-mcp.ts        # 派生 MCP 工具清单
│   ├── derive-prompt.ts     # 派生 MCP 技能清单（PromptDef + render）
│   └── resolve.ts           # 路径 / 参数解析
├── cli/                     # stock-sdk 命令行
├── mcp/                     # 内置 MCP server（零依赖手写协议）
│   ├── tools/               # 工具注册表（自 methods.ts 派生）
│   └── prompts/             # 技能注册表（自 prompts.ts 派生）
├── providers/               # 数据源适配层(只负责"取数 + 解析")
│   ├── index.ts             # 聚合导出 tencent / eastmoney / sina
│   ├── tencent/             # 行情、批量、搜索、交易日历、资金流
│   ├── eastmoney/           # K线、板块、分红、期货/期权、基金扩展、龙虎榜、大宗、融资、北向、涨停异动
│   └── sina/                # ETF / 股指 / 商品期权
├── sdk/                     # 服务层:按领域拆分的 Service 类(构造注入 RequestClient)
│   ├── baseService.ts       # service 基类
│   ├── quoteService.ts      # 实时行情
│   ├── klineService.ts      # K 线 / 分时(A / HK / US)
│   ├── boardService.ts      # 行业 / 概念板块
│   ├── indicatorService.ts  # 带指标 K 线 + 指标信号识别(组合 kline + quote + calcSignals)
│   ├── chipService.ts       # 筹码分布(组合 kline + 本地 CYQ 计算)
│   ├── futuresService.ts    # 期货
│   ├── optionsService.ts    # 期权
│   ├── fundFlowService.ts   # 资金流向(深度)
│   ├── northboundService.ts # 沪深港通 / 北向
│   ├── marketEventService.ts# 涨停 / 盘口异动
│   ├── dragonTigerService.ts# 龙虎榜
│   ├── fundService.ts       # 公募基金扩展(分红/净值/排名/档案)
│   ├── tradingCalendarService.ts # 交易日历 / 市场状态
│   ├── dataService.ts       # 代码列表/批量/搜索/分红/大宗/融资融券
│   └── index.ts             # 导出全部 service
├── types/                   # 公共类型(按领域模块化)
│   ├── quotes.ts / kline.ts / board.ts / fund.ts / fundFlow.ts
│   ├── northbound.ts / dragonTiger.ts / marketEvent.ts / blockTrade.ts
│   ├── margin.ts / futures.ts / options.ts / common.ts
│   └── index.ts
├── sdk.ts                   # StockSDK 门面类:v2 命名空间 getter + 顶层 search
├── externalLinks.ts         # 外部财经链接工具
└── index.ts                 # 主入口(StockSDK、subpath 再导出、类型、工具)

scripts/                     # 文档元数据、llms.txt 生成、git hooks
test/
├── unit/                    # 单元测试（含 cli/、mcp/、spec/、signals/、screener/ 等）
├── integration/             # 集成测试（真实网络请求）
├── mocks/                   # MSW Mock 配置
└── setup.ts                 # Vitest 测试初始化

website/                     # VitePress 文档
├── api/                     # 中文 API 文档
├── guide/                   # 中文指南（含 migration-v1-to-v2、symbols 等）
├── cli/                     # CLI 文档
├── mcp/                     # MCP 文档（含 skills）
├── playground/              # 在线示例（组件化，从 spec 派生）
├── en/                      # 英文文档（api / guide / cli / mcp / playground）
├── public/                  # 静态资源（含 llms.txt / llms-full.txt）
└── .vitepress/              # VitePress 配置与主题