cn-stock-toolbox

name	cn-stock-toolbox
description	cn-stock-toolbox - A-share query and portfolio management tool based on baostock
metadata	{"icon":"📈","requires":["uv"],"category":"finance","tags":["stock","a-share","baostock","portfolio"]}

cn-stock-toolbox Skill

A-share query tool based on baostock data source, providing portfolio management, market data query and other functions.

前置条件

必须安装

• uv: 用于管理Python环境和运行脚本
  • 安装方式: https://docs.astral.sh/guide/installation/

安装说明

# 1. 进入skill目录
cd /path/to/cn-stock-toolbox

# 2. 使用uv创建虚拟环境并安装依赖
uv sync

# 3. (可选，人类用户手动安装) 安装shell alias，方便直接使用
# chmod +x install.sh
# ./install.sh

命令参考

通用命令格式

# Skill模式（推荐，自动使用uv环境）
uv run scripts/cnstk.py <command> [options]

# 人类模式（需先运行install.sh安装alias）
cnstk <command> [options]

刷新股票基本信息

# 手动刷新股票基本信息
# ⚠️  注意：完整刷新股票数据可能需要较长时间（几分钟），请耐心等待
uv run scripts/cnstk.py refresh

关于刷新机制说明：

• 首次刷新：从未刷新过或距离上次刷新超过1个月时，会执行完整刷新（获取所有股票基本信息）
• 每日刷新：每次运行命令前，会自动执行差异刷新（仅更新数据库中不存在的新股票）
• 差异刷新：速度较快，仅获取最新股票列表并补充新增股票

刷新股票行业信息

# 全量刷新行业信息
# ⚠️  注意：该命令会逐只查询行业信息，可能耗时较长
uv run scripts/cnstk.py refresh-industries

• industry <code> 会优先读取本地缓存；若缓存中没有行业信息，则按需查询并写回 SQLite
• refresh 不再刷新行业信息，只刷新股票基础信息

灵活查询股票

# 按名称搜索
uv run scripts/cnstk.py search --name 科技

# 按行业搜索
uv run scripts/cnstk.py search --industry 半导体

# 按市场搜索（sh-上海, sz-深圳, bj-北京）
uv run scripts/cnstk.py search --market sh

# 按类型搜索（stock-股票, etf-ETF基金）
uv run scripts/cnstk.py search --type etf

# 组合条件搜索
uv run scripts/cnstk.py search --name 银行 --industry 金融

持仓管理

# 添加持仓
uv run scripts/cnstk.py portfolio add <股票代码> <数量> <买入价格> [买入日期]

# 示例
uv run scripts/cnstk.py portfolio add sh.600000 100 10.50 2024-01-01

# 删除持仓
uv run scripts/cnstk.py portfolio remove <持仓ID>

# 查看持仓列表
uv run scripts/cnstk.py portfolio list

# 查看持仓盈亏
uv run scripts/cnstk.py portfolio profit

股票查询

# 自动识别代码或名称查询
uv run scripts/cnstk.py stock query <股票代码或名称>

# 股票名称查代码
uv run scripts/cnstk.py stock name-to-code <股票名称>

# 股票代码查名称
uv run scripts/cnstk.py stock code-to-name <股票代码>

# 查询股票基本信息（支持代码或名称）
uv run scripts/cnstk.py stock info <股票代码或名称>

• stock query 会自动判断输入更像股票代码还是名称
• 如果名称不完整或匹配到多个股票，会输出候选列表供用户或 agent 继续选择
• 股票基本信息会附带最近可用交易日行情；如果当天不是交易日，会自动显示上个交易日行情并注明

行情查询

# 查询K线（默认最近60天日K）
uv run scripts/cnstk.py kline <股票代码>

# 指定时间范围和频率
uv run scripts/cnstk.py kline <股票代码> --start 2024-01-01 --end 2024-03-01 --freq d

# 频率选项: d-日K, w-周K, m-月K

# 查询指数信息
uv run scripts/cnstk.py index <指数代码>

# 常用指数代码:
# - sh.000001: 上证指数
# - sz.399001: 深证成指
# - sz.399006: 创业板指

# 查询交易日
uv run scripts/cnstk.py trading-day --date 2024-03-08

# 查询交易日范围
uv run scripts/cnstk.py trading-day --start 2024-01-01 --end 2024-03-01

# 查询股票所属行业
uv run scripts/cnstk.py industry <股票代码>

Agent使用指南

任务示例

1. 查询股票代码

用户: "帮我查一下贵州茅台的股票代码"
Agent:
  1. 使用: `uv run scripts/cnstk.py stock name-to-code 贵州茅台`
  2. 返回结果给用户

2. 管理持仓

用户: "我买入了100股招商银行，价格35元，帮我记录一下"
Agent:
  1. 使用: `uv run scripts/cnstk.py portfolio add sh.600036 100 35.00`
  2. 确认添加成功

3. 查看持仓盈亏

用户: "帮我看看现在持仓盈亏情况"
Agent:
  1. 使用: `uv run scripts/cnstk.py portfolio profit`
  2. 返回盈亏详情给用户

4. 查询K线

用户: "帮我看看腾讯最近30天的K线"
Agent:
  1. 使用: `uv run scripts/cnstk.py kline hk.00700 --start <30天前日期>`
  2. 返回K线数据

数据持久化

• SQLite数据库位置: data/portfolio.db
• 包含: 持仓记录、股票基本信息缓存
• 股票基本信息自动每日刷新

错误处理

常见错误及解决方法

1. baostock登录失败

   • 检查网络连接
   • 确认baostock服务正常

2. 数据库文件无法创建

   • 检查data目录权限
   • 确保有写入权限

3. 股票代码格式错误

   • 正确格式: sh.600000 (上海)、sz.000001 (深圳)、bj.800000 (北京)

Skill元数据

• 作者: xiaoski
• GitHub: https://github.com/xiaoski
• 项目地址: https://github.com/xiaoski/cn-stock-toolbox
• 版本: 0.1.0
• 数据源: baostock (http://baostock.com)
• 许可证: MIT