koishi-plugin-stock-market

Koishi 股票市场模拟插件

一个功能完整的 Koishi 股票投资模拟插件，提供真实的股票市场交易体验。

功能特性

📊 完整的股票市场系统

• 20只精选模拟股票，覆盖多个行业
• 实时价格波动（可配置更新间隔）
• 真实的涨跌幅限制（基于开盘价）
• 完整的股市指标（开盘价、最高价、最低价、成交量等）
• 自动交易时间控制（每日定时开市/收市）
• 周末自动休市
• 每日自动重置市场数据

💰 账户管理

• 用户开户系统
• 现金和持仓管理
• 实时资产计算
• 盈亏统计（基于累计入金）
• 数据库持久化存储

📈 交易功能

• 买入/卖出股票（仅交易时间可用）
• 交易手续费计算（支持最低手续费）
• 持仓成本追踪
• 交易记录查询
• 净盈亏计算（扣除手续费）

🏆 社交功能

• 资产排行榜（TOP 10）
• 多用户竞争
• 用户ID隐私保护

安装

# 在 Koishi 项目的目录下安装
npm install koishi-plugin-stock-market

配置

在 Koishi 配置文件中添加插件：

plugins:
  stock-market:
    initialCash: 100000          # 初始资金（元）
    tradeFee: 0.003             # 交易手续费率（0.3%）
    minFee: 5                   # 最低手续费（元）
    minTradeAmount: 1000        # 最小交易金额（元）
    updateInterval: 5           # 市场更新间隔（分钟）
    maxChangePercent: 0.10      # 单日最大涨跌幅（10%）
    enableMarket: true           # 是否启用市场
    marketOpenHour: 9           # 开市时间（小时）
    marketOpenMinute: 30        # 开市时间（分钟）
    marketCloseHour: 15         # 收市时间（小时）
    marketCloseMinute: 0        # 收市时间（分钟）
    enableAutoReset: true       # 是否启用每日自动重置市场

指令说明

账户相关

指令	说明
股票开户	开通股票账户，获得初始资金
我的账户	查看账户余额、持仓和盈亏
交易记录	查看最近的交易记录

市场相关

指令	说明
股票市场	查看市场整体状态
股票列表	查看所有股票信息
股票列表 <关键词>	按股票代码、名称或行业搜索
股票查询 <代码>	查看单只股票的详细信息

交易相关

指令	说明
股票买入 <代码> <数量>	买入指定数量的股票
股票卖出 <代码> <数量>	卖出指定数量的股票

其他

指令	说明
股票排行	查看资产排行榜 TOP 10
股票帮助	显示所有指令帮助

交易规则

• 最小交易单位: 股票交易数量必须是 100 股的整数倍（1 手 = 100 股）
• 交易手续费: 每笔交易收取 max(交易金额 × 手续费率, 最低手续费) 的手续费
• 最小交易金额: 单笔交易金额不能低于配置的最小限制（默认 1000 元）
• 涨跌幅限制: 单日涨跌幅限制为 ±10%（基于开盘价），价格会被严格限制在此范围内
• 交易时间: 仅在配置的交易时间内（默认 9:30-15:00）可以进行交易
• 周末休市: 周六、周日自动休市，无法交易
• 市场更新: 市场价格每 5 分钟（可配置）自动更新一次
• 盈亏计算: 显示的盈亏为净盈亏，已扣除交易手续费
• 数据持久化: 所有账户、持仓、交易记录都会保存到数据库

股票列表

代码	名称	行业
000001	平安银行	银行
000002	万科A	房地产
000858	五粮液	白酒
000876	新希望	农业
300750	宁德时代	新能源
300059	东方财富	证券
601318	中国平安	保险
600519	贵州茅台	白酒
600036	招商银行	银行
601888	中国中免	旅游零售
000725	京东方A	电子
002415	海康威视	安防
601012	隆基绿能	光伏
600690	海尔智家	家电
000333	美的集团	家电
002594	比亚迪	汽车
601919	中远海控	航运
600276	恒瑞医药	医药
300760	迈瑞医疗	医疗器械

价格波动机制

股票价格采用随机波动模型，基于以下因素：

• 基准价格: 每只股票都有基准价格，价格不会低于基准价格的 50%
• 波动率: 每只股票有不同的波动率，反映其历史波动特性
• 涨跌幅限制: 单日涨跌幅限制为配置的百分比（默认 10%），价格严格限制在 [open * (1 - maxChangePercent), open * (1 + maxChangePercent)] 范围内
• 趋势判断: 根据涨跌幅判断当前趋势（上涨 >3% / 下跌 <-3% / 震荡）
• 成交量模拟: 成交量根据价格变动幅度动态生成，价格变动越大成交量越大
• 每日重置: 每个交易日自动重置开盘价、最高价、最低价和涨跌幅

使用示例

用户: 股票开户
Bot: 🎉 股票账户开通成功！
     💰 初始资金: 100000.00 元
     📊 使用 "股票帮助" 查看更多指令

用户: 股票列表 白酒
Bot: 📊 股票列表
     ━━━━━━━━━━━━━━━━
     ⚪ 000858 五粮液
         价格: 180.50 | 涨跌: +0.00 (+0.00%)
         ...

用户: 股票买入 000858 100
Bot: ✅ 买入成功！五粮液 100 股，价格: 180.50 元，手续费: 54.15 元

用户: 我的账户
Bot: 👤 我的股票账户
     ━━━━━━━━━━━━━━━━
     💰 现金余额: 99845.85 元
     📊 持仓市值: 18050.00 元
     ...

开发

# 克隆项目
git clone <repository-url>
cd koishi-plugin-stock-market

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

技术架构

• TypeScript: 类型安全的开发体验
• Koishi Framework: 基于 Koishi 4.x 生态
• 数据库持久化: 使用 Koishi 数据库 API 存储账户、持仓和交易记录
• 模块化设计: 清晰的代码结构，易于扩展
• 异步操作: 关键交易操作使用 async/await 确保数据一致性

数据结构

Stock（股票）

{
  code: string          // 股票代码
  name: string          // 股票名称
  industry: string      // 所属行业
  basePrice: number     // 基准价格
  price: number         // 当前价格
  open: number          // 开盘价
  high: number          // 最高价
  low: number           // 最低价
  change: number        // 涨跌额
  changePercent: number // 涨跌幅
  volume: number        // 成交量（手）
  turnover: number      // 成交额（万）
  volatility: number    // 波动率
  trend: 'bull' | 'bear' | 'neutral' // 趋势
  lastVolume: number    // 上次成交量
}

UserAccount（用户账户）

{
  userId: string        // 用户ID
  cash: number          // 现金余额
  totalDeposit: number  // 累计入金总额
  totalAssets: number   // 总资产
  profit: number        // 总盈亏（基于累计入金）
  profitPercent: number // 盈亏比例
  createTime: number    // 开户时间
  lastTradeTime: number // 最后交易时间
}

TradeRecord（交易记录）

{
  id: string            // 记录ID（时间戳+随机数）
  userId: string        // 用户ID
  stockCode: string     // 股票代码
  stockName: string     // 股票名称
  type: 'buy' | 'sell'  // 交易类型
  price: number         // 交易价格
  shares: number        // 交易数量
  amount: number        // 交易金额
  fee: number           // 手续费
  netAmount: number     // 净金额
  profit: number        // 净盈亏（仅卖出时）
  time: number          // 交易时间
}

数据库表结构

插件使用 Koishi 数据库存储以下数据：

表名	说明
stock_account	用户账户信息
stock_position	用户持仓信息
stock_trade	交易记录

更新日志

v1.1.0

• ✅ 新增数据库持久化支持，数据不再丢失
• ✅ 新增交易时间控制（可配置开市/收市时间）
• ✅ 新增周末自动休市功能
• ✅ 新增每日自动重置市场数据
• ✅ 新增最低手续费配置
• ✅ 优化涨跌幅限制逻辑，严格限制在日内范围内
• ✅ 优化手续费计算，确保净盈亏显示正确
• ✅ 优化成交量生成，与价格变动幅度相关
• ✅ 优化账户盈亏计算，基于累计入金而非固定初始资金
• ✅ 优化排行榜用户ID显示，保护用户隐私
• ✅ 修复股票搜索大小写敏感问题
• ✅ 修复交易数量为0时的边界检查
• ✅ 降低日志输出频率

v1.0.0

• 🎉 初始版本发布
• ✅ 基础股票市场功能
• ✅ 账户管理
• ✅ 交易功能
• ✅ 排行榜

License

MIT