name: stock-dev description: StockBuddy 项目开发导航。覆盖 Electron/React 结构、stock-sdk 数据源、Provider/Service 数据流、IPC 通道、数据库、测试与编码规范。 argument-hint: '[开发任务描述]'
StockBuddy 开发技能
本技能是项目开发导航和速查手册。开发新功能、修改数据层、接入数据源、调整 UI/IPC 前，先按本文件确认项目结构与强制规范。
1. 必读规则与优先级
开始编码前必须阅读并遵守 .claude/rules/ 下的规则文件：
| 优先级 | 规则文件 | 适用场景 |
| ------ | ----------------------------------- | ---------------------- |
| 1 | .claude/rules/typescript-react.md | 所有 TS/TSX/React 代码 |
| 2 | .claude/rules/data.md | 行情、数据访问、存储 |
| 3 | .claude/rules/emoji.md | AI 投研输出、文案 |
| 4 | .claude/rules/bug-fix.md | Bug 修复 |
核心红线：
- 真实数据优先：面向用户的股票、行情、板块、新闻、图表、投研响应必须使用真实数据。
- 数据源优先级：
stock-sdk→a-stock-data skill→ 明确空状态/错误状态/加载状态。 - 禁止伪造 fallback：不得使用 fake/mock/preview/demo/sample/hardcoded 行情、新闻、K 线、板块排行或合成走势图。
- 统一数据流：UI → Service → Provider → Data Source；React 组件不得直接请求第三方行情接口。
- 类型安全：禁止新增
any、as any、as unknown as、@ts-ignore；优先补类型和泛型。 - 精准修改：不得改动需求之外的文件、逻辑和公共 API。
- 金融计算：禁止用浮点数做金额/收益等金融计算；必要时使用整数单位或可靠数值工具。
2. 当前项目结构
src/ # React 渲染进程
app.tsx # 主布局、主视图路由、右侧栏入口、全局 ErrorBoundary
store/app-store.ts # Zustand 全局状态；MainView/RightPanelTab 等 UI 状态
shared/
stocksense-api.ts # 渲染进程数据门面；Electron: window.stocksense → IPC；Browser: 空/错误状态
types.ts # 渲染/主进程共享类型
analytics.ts # 前端埋点
hooks/ # 组件级/应用级 hooks
components/
chat-view/ # AI 对话区
discovery-view/ # 探索页：市场摘要、情绪、涨停复盘、龙虎榜、AI 监控等
market-view/ # 行情页：指数卡片、行情表格、指数 K 线弹层
news-reader/ # 新闻详情阅读器
stock-detail-panel/ # 右侧栏：收藏、个股、板块、异动、新闻、AI 监控
kline-chart/ # K 线图表
error-boundary/ # React 错误边界
electron/ # Electron 主进程
main.ts # Electron 启动入口
preload.cjs # contextBridge 暴露 window.stocksense；新增 IPC 时需同步
ipc.ts # IPC handler 注册中心
services/
stock/ # 股票、板块、新闻、探索、监控、投研数据服务
stock-client.ts # 股票详情、搜索、K 线、批量行情、分时等聚合入口
shared.ts # stock-sdk 实例、通用请求/格式化工具
market-page.ts # 行情页快照
discovery-service.ts # 探索页快照聚合
discovery-*.ts # 探索页分模块数据
monitor-service.ts # AI 监控数据
monitor-history-store.ts # AI 监控历史 DuckDB
trading-advice-service.ts # AI 交易建议
news-client.ts # 新闻、公告、新闻摘要
board-detail.ts # 板块详情
fund-flow.ts # 个股资金流
hot-focus.ts # 热点/异动/板块资金流
hot-stock-hints-service.ts # 热点股票提示
surge-history-*.ts # 异动历史存储/调度/服务
quote-store.ts # SQLite 实时行情缓存
chip-distribution.ts # 筹码分布
indicators.ts # 技术指标
symbols.ts # 股票/板块代码标准化
schemas.ts # 数据 schema/校验
format.ts # 数值格式化
market-data/ # DuckDB 市场数据持久层
market-data-store.ts # DuckDB 表结构 + CRUD
market-data-query.ts # 本地优先查询入口
market-data-sync.ts # K 线同步调度
data-sync-handlers.ts # 同步按钮触发的任务
providers.ts # 市场数据 Provider
quality.ts # 数据质量检查
trade-date-resolver.ts # 交易日解析
agent/ # AI Agent 系统
orchestrator.ts # Chat 核心编排入口
dag-executor.ts # DAG 执行器
intent-routing.ts # 意图路由
analysis-agent.ts # 技术/结构化分析 Agent
data-agent.ts # 数据获取 Agent
report-agent.ts # 报告生成 Agent
risk-agent.ts # 风险 Agent
compliance-critic.ts # 合规/伪造数据/Emoji 检查
evidence.ts # 证据链工具
agent-tool-runtime.ts # Agent 工具运行时
tools/ # Agent Tool 注册与股票工具
llm/ # LLM 客户端与埋点
selfchecks/ # Electron/Node 自检脚本
主视图路由
MainView 定义在 src/store/app-store.ts：
| MainView | 组件 | 说明 |
| --------------- | ------------------- | ----------------------------------------- |
| 'chat' | <ChatView /> | 默认 AI 对话视图 |
| 'market' | <MarketView /> | 行情页 |
| 'discovery' | <DiscoveryView /> | 探索页/监控/复盘 |
| 'news-reader' | <NewsReader /> | 新闻阅读覆盖视图；关闭后恢复 previousView |
新增主视图时通常需要同步：
src/store/app-store.ts的MainView类型与状态方法。src/app.tsx的 ErrorBoundary 名称和组件分支。- 入口按钮/侧边栏逻辑。
- 必要的埋点、测试和空状态。
3. 数据访问与 Provider 规则
3.1 标准数据流
React Component
↓ getStocksenseApi().someMethod()
src/shared/stocksense-api.ts
↓ window.stocksense.someMethod() [Electron] / empty-or-error [Browser]
electron/preload.cjs
↓ ipcRenderer.invoke('channel:name')
electron/ipc.ts
↓ service function
electron/services/**
↓ stock-sdk / a-stock-data skill / DuckDB / SQLite / LLM
Data Source
要求：
- React 组件只调用
getStocksenseApi()或已有 service/hook，不直接fetch东财、腾讯、Tushare 等第三方接口。 - 新增第三方数据访问必须放在 Electron service/provider 层。
- Browser/PWA fallback 只能返回空状态、错误状态、加载状态，或调用真实 API；不得展示预览行情/模拟 K 线/示例新闻。
- 图表必须有真实序列才渲染；没有真实 K 线/分时数据时显示“暂无图表数据”。
- 搜索/自动补全必须支持代码和名称部分匹配，优先
stock-sdk，其次a-stock-data skill。
3.2 stock-sdk 使用原则
项目已依赖 stock-sdk，新增或修改股票数据接口时先查：
- API 文档：https://stock-sdk.linkdiary.cn/api/
- skills 文档：https://stock-sdk.linkdiary.cn/skills/catalog
常见能力：
| 能力 | 优先入口/说明 |
| --------------- | ---------------------------------------------- |
| A 股行情 | sdk.quotes.cn(codes)，批量优先 |
| 搜索 | sdk.search(keyword) |
| 历史 K 线 | sdk.kline.cn(symbol, opts) |
| 板块/行业 | sdk.board.industry / sdk.board.concept |
| 资金流 | sdk.fundFlow.* |
| 市场异动/涨停池 | sdk.marketEvent.* |
| 筹码分布 | sdk.chips.cn(symbol, opts) |
| 交易日历 | sdk.calendar.isTradingDay / prevTradingDay |
实践要求：
- 批量接口优先，避免逐个请求。
- 远程请求必须有超时、错误暴露和用户可理解的错误/空状态。
- 同参数高频请求应复用缓存或 in-flight Promise。
- 如果
stock-sdk不支持或返回空，再考虑a-stock-data skill。 - 如果所有真实数据源都不可用，返回空/错误，不得合成假数据。
3.3 a-stock-data 使用原则
a-stock-data 是次级真实数据源能力，适用于 stock-sdk 无接口、不适合当前场景或暂不可用的情况。
- 使用前先确认
stock-sdk是否已有能力。 - 不得把 a-stock-data 失败降级为 mock/fake 数据。
- 如果输出中存在
warnings/source字段，应标明真实数据来源。 - 所有东财/腾讯等直接 HTTP 接入都必须封装在 service/provider 层，不能散落到 UI。
4. 本地数据库与缓存
4.1 市场数据 DuckDB
文件：electron/services/market-data/market-data-store.ts
| 表名 | 用途 |
| ------------------------ | ------------------ |
| securities | A 股证券主表 |
| trade_calendar | 交易日历 |
| daily_bars | 日线 K 线 |
| sync_jobs | 同步任务记录 |
| sync_failures | 同步失败详情 |
| market_board_snapshots | 板块/行情快照 JSON |
| discovery_snapshots | 探索页快照缓存 |
| stock_chips | 筹码分布缓存 |
| stock_snapshots | 实时行情快照 |
| market_board_details | 板块详情缓存 |
| market_boards | 板块列表 |
| board_constituents | 板块成分股 |
常用入口：
market-data-query.ts：本地优先查询，例如历史 K 线/最新行情。market-data-sync.ts：同步状态、启动、取消、重试失败。data-sync-handlers.ts：UI 手动同步入口。providers.ts：市场数据 Provider。
4.2 异动与监控 DuckDB
| 文件 | 表名 | 用途 |
| -------------------------------------------------- | -------------------- | ---------------------------- |
| electron/services/stock/surge-history-store.ts | stock_surge_events | 异动/涨停/跌停/炸板/强势历史 |
| electron/services/stock/monitor-history-store.ts | ai_monitor_events | AI 监控事件历史 |
4.3 SQLite
| 文件 | 数据库/表 | 用途 |
| ----------------------------------------- | ------------------------------------------------------ | ------------ |
| electron/services/conversation-store.ts | stocksense-chat.sqlite / conversations, messages | 会话和消息 |
| electron/services/stock/quote-store.ts | stocksense-quotes.sqlite / stock_quote | 实时行情缓存 |
实时行情存储规则：
Memory Cache → 15~30 秒批量写入 SQLite → UI 读取优先 Memory/本地，再远程补齐
禁止收到每条行情立即写库。
5. IPC 与 stocksenseApi 速查
5.1 新增 API 必改位置
新增渲染进程可调用能力时，按顺序同步：
src/shared/types.ts：共享类型与StocksenseApi接口。src/shared/stocksense-api.ts：Electron 门面和 Browser fallback（空/错误状态，不造假数据）。electron/preload.cjs：contextBridge.exposeInMainWorld('stocksense', api)中暴露方法。electron/ipc.ts：注册ipcMain.handle('channel:name', handler)。electron/services/**：真实数据 service/provider 实现。- 调用方组件/hook：通过
getStocksenseApi()调用。 - 测试或 selfcheck：覆盖关键成功/失败/空状态。
5.2 常用 IPC Channel
| 分类 | Channel | 说明 |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 配置/运行时 | config:get, config:set, config:testModel, app:getRuntimeInfo | 应用配置、模型测试、版本信息 |
| 收藏 | favorite:list, favorite:upsert, favorite:remove, favorite:togglePin | 收藏股票 |
| 会话 | conversation:list/create/delete/rename, message:list/save, chat:send | 会话、消息、AI 聊天 |
| 股票 | stock:getDetail, stock:search, stock:getKline, stock:getChipDistribution, stock:getBatchQuotes, stock:getTimelines | 个股、搜索、K 线、筹码、行情、分时 |
| 板块/行情 | board:getDetail, market:getPageSnapshot | 板块详情、行情页快照 |
| 探索/监控 | discovery:getSnapshot, monitor:getFeed, trading-advice:get | 探索页、AI 监控、交易建议 |
| 热点/异动 | hot:list, hot:hintSource, hot:historyDates, hot:history, stock:surgeEvents | 热点、异动历史、个股异动 |
| 新闻 | news:list, news:stockList, news:stockFeed, news:stockPreferences, news:getSummary, news:getDetail | 新闻和公告 |
| 数据同步 | marketData:getStatus, marketData:startSync, marketData:retryFailures, marketData:cancelSync, marketData:getStats, dataSync:* | 市场数据同步 |
| 存储/升级 | storage:getStats, storage:clear, system:getDiskInfo, appUpdate:* | 存储管理、应用升级 |
| 商店 | store:list, store:installed, store:install, store:uninstall | 命令/扩展商店 |
5.3 Push 事件
| Channel | 说明 |
| ---------------------------- | -------------------------------------- |
| chat:token | AI SSE token / runEvent 推送 |
| notification:aiResponse | AI 回复完成的应用内兜底通知 |
| market:pageSnapshotUpdated | 行情页快照更新 |
| marketData:progress | 市场数据同步进度 |
| storage:clearProgress | 存储清理进度 |
| favorite:cleared | 收藏被清空 |
| appUpdate:stateChanged | 应用升级状态变化 |
| dataSync:taskProgress | 数据同步任务进度（preload 已暴露监听） |
6. 主要前端模块约定
6.1 组件组织
- React 组件文件原则上只维护一个主组件。
- 子组件放当前目录
components/子目录。 - 单组件文件超过 400 行应拆分；超过 500 行必须拆分。
- 复杂逻辑提取 hook 或纯函数；单 hook 不超过 300 行。
- 大列表优先复用项目已有虚拟列表方案；当前依赖包含
@tanstack/react-virtual。 - 复杂组件外层应包
ErrorBoundary，现有主布局已对主区/右侧栏/弹层做保护。
6.2 重点模块
| 模块 | 入口 | 注意事项 |
| -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 行情页 | src/components/market-view/index.tsx | 子组件在 market-view/components/；数据来自 getMarketPageSnapshot 和 push 更新 |
| 探索页 | src/components/discovery-view/index.tsx | 数据来自 getDiscoverySnapshot、getMonitorFeed、getTradingAdvice；不得在组件里拼假榜单 |
| 右侧栏 | src/components/stock-detail-panel/index.tsx | 面板子组件放 components/；右侧 tab 定义在 app-store |
| K 线 | src/components/kline-chart/ | 只能渲染真实序列；无数据展示空状态 |
| 新闻阅读 | src/components/news-reader/ | news-reader 是覆盖视图，关闭需恢复 previousView |
7. AI Agent 与投研输出约定
主要入口：
electron/services/agent/orchestrator.ts：聊天请求入口。electron/services/agent/intent-routing.ts：命令/意图识别。electron/services/agent/dag-executor.ts：多 Agent 流程执行。electron/services/agent/evidence.ts：证据链聚合。electron/services/agent/compliance-critic.ts：合规检查。electron/services/tools/stock-tools.ts：股票工具。
要求：
- 投研报告必须基于证据链和真实数据源；缺数据要明确“暂无数据/数据源暂不可用”。
- 不得输出确定性买卖指令；必须保留风险提示。
- Emoji 遵守
.claude/rules/emoji.md，保持专业金融风格；禁止娱乐化/炒作型 Emoji。 - Agent fallback 文案可以提示数据不可用，但不得生成虚假市场数值。
8. 新增功能 Checklist
开发全新页面、面板、数据展示、IPC/API 时按以下顺序：
- 确认数据源：先查
stock-sdk文档和现有 service/provider；不支持再考虑a-stock-data skill。 - 确认类型：优先复用
src/shared/types.ts现有类型；新增类型遵守I*interface /T*type 命名。 - Service/Provider：在
electron/services/**实现真实数据逻辑；异步失败路径要暴露并处理。 - IPC/Preload/API：同步
types.ts→stocksense-api.ts→preload.cjs→ipc.ts。 - Browser fallback：只能返回空状态/错误状态/加载状态，或真实 API 数据；不得造假。
- UI 组件：放入对应
src/components/<feature>/；子组件放components/；主组件加空/错/加载状态。 - 状态管理：如需全局状态，扩展
src/store/app-store.ts；不得新增状态管理库。 - 验证：运行针对性单测/selfcheck/typecheck；说明未运行项和原因。
9. Bug 修复 Checklist
修 Bug 必须优先定位根因，不得隐藏错误或删除业务逻辑。修改前先回答：
- Bug 的根因是什么？
- 为什么会发生？
- 为什么当前实现失效？
- 修复是否影响其他功能？
- 是否引入新的性能问题？
- 是否改动了需求之外的地方？
- 是否引入新的问题？
完成后按以下格式说明：
### Root Cause
### Fix
### Impact
### Risk
### Verification
修 Bug 优先使用 stock-fix-bug skill。
10. 编码规范速查
命名
- 文件/目录：
kebab-case。 - Interface：
I+ PascalCase。 - Type：
T+ PascalCase。 - Enum：PascalCase。
禁止事项
any/as any/as unknown as/@ts-ignore/ 降低 tsconfig 严格度。- React 组件直接请求第三方行情 API。
- 用
catch { return [] }、catch { return null }、catch { return {} }隐藏错误。 - 用 fallback/mock/fake/preview/demo/sample 数据掩盖数据源失败。
- 为消除 Hook 警告删除依赖项。
- 收到每条行情立即写库。
- 关键列表使用 index/random/频繁变化值作为 key。
- 新增状态管理库。
- 改动需求之外的代码。
必须做到
- React Hook 依赖完整，分析闭包和状态同步。
- 异步函数处理失败路径并给出可理解错误/空状态。
- 类型表达业务含义，公共类型放共享位置。
- 未使用 import/变量/函数及时清理。
- 修改公共 API 类型时说明影响范围。
11. 常用命令
pnpm dev # 启动 Electron 开发模式
pnpm dev:web # 启动 Vite 浏览器预览（不得展示假行情）
pnpm test # 运行 Vitest
pnpm test:watch # Vitest watch
pnpm test:coverage # 测试覆盖率
pnpm typecheck # TS 类型检查：renderer + node
pnpm build # typecheck + Vite + Electron build
pnpm selfcheck:market-data # 市场数据库自检
pnpm selfcheck:market-page # 行情页自检
pnpm selfcheck:index-kline # 指数 K 线自检
pnpm selfcheck:board-detail # 板块详情自检
pnpm selfcheck:chip-distribution # 筹码分布自检
pnpm selfcheck:market-review # 市场复盘自检
pnpm selfcheck:discovery-service # 探索服务自检
pnpm selfcheck:orchestrator # Agent 编排器自检
pnpm selfcheck:trade-date # 交易日解析自检
pnpm selfcheck:surge-monitor # 异动监控自检
pnpm selfcheck:monitor-service # AI 监控服务自检
pnpm selfcheck:ai-monitor-history # AI 监控历史自检
pnpm selfcheck:news-summary # 新闻摘要自检
pnpm selfcheck:hot-stock-hints # 热点股票提示自检
pnpm selfcheck:trading-advice # 交易建议自检
12. 相关技能
| 技能 | 用途 |
| --------------- | --------------------------------------------------- |
| stock-fix-bug | Stock Agents Bug 修复：根因定位、最小改动、验证闭环 |
| a-stock-data | stock-sdk 不覆盖或不适合时的次级真实数据源能力 |
| code-review | 代码审查 |
| simplify | 对已改代码做复用、简化、效率和技术债清理 |
| klinecharts | K 线图表相关实现参考 |
13. 历史风险提醒
项目历史上存在过 preview/fallback/hardcoded 数据模式。后续触碰相关文件时不得扩展这些模式，应逐步替换为真实数据源或明确空/错状态：
src/shared/stocksense-api.ts：Browser fallback 必须谨慎，不能加入假行情/假新闻/假榜单。electron/services/stock/stock-client.ts：不得新增合成行情、合成指数、伪造板块数据。src/components/kline-chart/index.tsx：不得根据单个价格或涨跌幅生成走势图。- Agent fallback 文案只能表达数据不可用，不能伪造市场数值。
14. 单元测试
- 所写的重点逻辑代码必须有单元测试覆盖。
- 测试代码需放在
__tests__/目录下, 文件名以*.test.ts`结尾。 - 单元测试的describe和it 都需要使用中文来编写
Next.js App Router Expert
Development
A skill that turns Claude into a Next.js App Router expert.
README Generator
Development
Creates professional and comprehensive README.md files for your projects.
API Documentation Writer
Development
Generates comprehensive API documentation in OpenAPI/Swagger format.