Vibe-Trading 可转债数据接入指南：使用 Tushare cb_issue 接口获取可转债发行数据

本文是一份面向 Vibe-Trading 仓库内 tushare 数据技能库（agent/src/skills/tushare/SKILL.md）的实操型技术文档，聚焦"可转债发行"数据接口 cb_issue：从接口权限、输入输出字段、调用示例到与可转债生命周期其它接口的联动用法，手把手教你用 Python 快速取数，并将发行数据接入可转债投研工作流。读完本文，你将能够独立完成 Tushare 环境配置、按公告日/日期区间/自定义字段提取全量可转债发行记录，并结合可转债基础信息、行情与赎回数据搭建可转债跟踪管线。

一、接口总览：cb_issue 能做什么

cb_issue 是 Tushare Pro 中专门用于获取可转债发行数据的接口，与可转债基础信息（cb_basic）、可转债行情（cb_daily）、可转债赎回信息（cb_call）、可转债转股价变动（cb_price_chg）、可转债转股结果（cb_share）共同构成 Vibe-Trading tushare 技能库"债券专题"下的可转债数据矩阵（见 agent/src/skills/tushare/references/债券专题）。

在 Vibe-Trading 中，tushare 被 agent/src/skills/data-routing/SKILL.md 明确登记为 A股、基金、期货、宏观 领域的首选数据源之一（对应环境变量 TUSHARE_TOKEN），并标注为"China network"（需在中国网络环境下访问）。对于 A 股可转债这一资产类别，cb_issue 提供的是发行环节的全量结构化数据：既包含计划发行总额、发行总额、发行价格、发行方式等基本面要素，也覆盖网上发行、老股东配售、网下发行三大认购渠道的申购代码、日期、有效申购数量/户数、超额认购倍数与中签率，以及主承销商及其包销数量。

接口核心约束（来自文档原文）：

项目	说明
接口名	cb_issue
描述	获取可转债发行数据
限量	单次最大 2000 条，可多次提取，总量不限制
积分	用户需要至少 2000 积分才可以调取；5000 积分以上频次相对较高，积分越多权限越大（积分获取办法详见 Tushare 官方文档对应章节）

也就是说，只要积分达标，就可以通过日期区间循环分页的方式将全历史可转债发行数据全部拉取下来，不受总量限制——文档数据示例中甚至包含 1998 年发行的老券记录，佐证了该接口覆盖早期历史数据。

二、环境准备：安装 tushare 并配置 Token

调用 cb_issue 之前，需要先完成 tushare 环境初始化。Vibe-Trading 的 tushare 技能文档（agent/src/skills/tushare/SKILL.md）给出了标准步骤：

1. 安装 Python 运行环境（推荐 Python 3.7+），并从清华 PyPI 镜像安装 tushare：

pip install tushare -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 注册 Tushare 账号获取 token，并配置环境变量：

export TUSHARE_TOKEN=your_token

3. 在代码中读取 token 并初始化 Pro 接口。Vibe-Trading 的示例脚本 agent/src/skills/tushare/scripts/stock_data_example.py 展示了两种 token 来源的兼容写法：

import os
import tushare as ts

# 读取环境变量中的 token, 或者读取本地记录的 token
token = os.getenv('TUSHARE_TOKEN') or ts.get_token()

# 初始化pro接口实例
pro = ts.pro_api(token)

在 Vibe-Trading 的工程化环境里，TUSHARE_TOKEN 属于受管凭据：后端 agent/src/api/settings_routes.py 定义了 tushare_token_configured、tushare_token_hint 等状态字段以及 token 更新接口，并把 TUSHARE_TOKEN 与占位符（如 your-tushare-token）一并纳入安全校验逻辑，避免占位符被误当作真实凭据。这意味着你在 Vibe-Trading 中既可以用系统环境变量，也可以通过设置接口持久化管理 token，两条路径在 ts.pro_api() 层面等价。

三、输入参数详解

cb_issue 的输入参数全部为可选（必选均为 N），共 4 个，可按"单券精确查询"或"日期区间批量查询"两种思路使用：

名称	类型	必选	描述
ts_code	str	N	TS代码（转债代码）
ann_date	str	N	发行公告日
start_date	str	N	公告开始日期
end_date	str	N	公告结束日期

使用要点：

• 日期格式统一为 YYYYMMDD（如 20190612、20200814），与 tushare 技能库的通用参数约定一致（见 SKILL.md "参数格式说明"：日期 YYYYMMDD、股票代码 ts_code 如 000001.SZ / 600000.SH、返回格式 pandas DataFrame）。
• 按公告日精确查询：传 ann_date='20190612'，可获取该公告日当天公告发行的全部可转债。
• 按区间查询：传 start_date + end_date 组合，适合批量回补历史数据，再配合"单次最大 2000 条"的限制按区间分页循环，即可突破单次行数上限、实现总量不限制的全量提取。

四、输出参数详解：38 个字段全景

cb_issue 返回的字段可划分为五组，覆盖可转债发行的完整流程。其中"默认显示"为 Y 的字段是接口默认返回的核心列，N 为可选扩展列。

4.1 发行基础信息

名称	类型	默认显示	描述
ts_code	str	Y	转债代码
ann_date	str	Y	发行公告日
res_ann_date	str	Y	发行结果公告日
plan_issue_size	float	Y	计划发行总额（元）
issue_size	float	Y	发行总额（元）
issue_price	float	Y	发行价格
issue_type	str	Y	发行方式
issue_cost	float	N	发行费用（元）

4.2 网上发行（申购）渠道

名称	类型	默认显示	描述
onl_code	str	Y	网上申购代码
onl_name	str	Y	网上申购简称
onl_date	str	Y	网上发行日期
onl_size	float	Y	网上发行总额（张）
onl_pch_vol	float	Y	网上发行有效申购数量（张）
onl_pch_num	int	Y	网上发行有效申购户数
onl_pch_excess	float	Y	网上发行超额认购倍数
onl_winning_rate	float	N	网上发行中签率（%）

4.3 老股东配售渠道

名称	类型	默认显示	描述
shd_ration_code	str	Y	老股东配售代码
shd_ration_name	str	Y	老股东配售简称
shd_ration_date	str	Y	老股东配售日
shd_ration_record_date	str	Y	老股东配售股权登记日
shd_ration_pay_date	str	Y	老股东配售缴款日
shd_ration_price	float	Y	老股东配售价格
shd_ration_ratio	float	Y	老股东配售比例
shd_ration_size	float	Y	老股东配售数量（张）
shd_ration_vol	float	N	老股东配售有效申购数量（张）
shd_ration_num	int	N	老股东配售有效申购户数
shd_ration_excess	float	N	老股东配售超额认购倍数

4.4 网下发行渠道

名称	类型	默认显示	描述
offl_size	float	Y	网下发行总额（张）
offl_deposit	float	N	网下发行定金比例（%）
offl_pch_vol	float	N	网下发行有效申购数量（张）
offl_pch_num	int	N	网下发行有效申购户数
offl_pch_excess	float	N	网下发行超额认购倍数
offl_winning_rate	float	N	网下发行中签率

4.5 承销与包销

名称	类型	默认显示	描述
lead_underwriter	str	N	主承销商
lead_underwriter_vol	float	N	主承销商包销数量（张）

字段口径提示：plan_issue_size（计划发行总额）与 issue_size（实际发行总额）可能存在差异（实际发行往往略有缩量）；三渠道中网上发行金额单位在"元"级别字段（plan_issue_size/issue_size）与"张"级别字段（onl_size/shd_ration_size/offl_size）之间并不一致，使用时要按字段描述核对单位，避免量纲错配。

五、接口调用示例

文档原文给出了两个最小可用示例，此处补充完整的环境初始化和分页提取写法，使其开箱即用：

5.1 按公告日提取（文档原例）

pro = ts.pro_api()

# 获取可转债发行数据
df = pro.cb_issue(ann_date='20190612')

# 获取可转债发行数据，自定义字段
df = pro.cb_issue(fields='ts_code,ann_date,issue_size')

5.2 按日期区间分页全量提取（实战扩展）

由于单次最多 2000 条，全量回补建议按年/按月循环，并用 start_date、end_date 划定窗口：

import time
import tushare as ts
import pandas as pd

pro = ts.pro_api()  # 或 ts.pro_api(os.getenv('TUSHARE_TOKEN'))

frames = []
for year in range(2020, 2025):
    df = pro.cb_issue(
        start_date=f'{year}0101',
        end_date=f'{year}1231',
        fields='ts_code,ann_date,res_ann_date,plan_issue_size,issue_size,'
               'issue_price,issue_type,onl_code,onl_date,onl_winning_rate,'
               'shd_ration_ratio,shd_ration_size,offl_size,lead_underwriter'
    )
    print(f'{year}: {len(df)} 条')
    frames.append(df)
    time.sleep(0.5)  # 控制请求频率，避免触发频控

all_issues = pd.concat(frames, ignore_index=True)

说明：fields 参数支持任意白名单字段组合，只取所需列可显著降低响应体量；time.sleep 是应对"频次与积分挂钩"的稳妥做法——5000 积分以上频次相对较高，但控制节奏仍是数据管线的基本素养。

六、返回数据示例解读

文档附带的真实数据片段如下（摘录）：

        ts_code  ann_date  issue_size
0    110072.SH  20200814     33.7000
1    113600.SH  20200811      5.9500
2    113598.SH  20200729      3.3000
3    113038.SH  20200729    50.0000
4    128125.SZ  20200728      4.5000
..         ...       ...        ...
489  100009.SH  20000223    13.5000
490  125302.SZ  19990727    15.0000
491  125301.SZ  19980826     2.0000
492  100001.SH  19980730     1.5000
493  125009.SZ      None      5.0000

从中可以读出三个关键信息：

1. 代码后缀区分交易所：.SH 为上交所可转债（如 110072.SH、113600.SH），.SZ 为深交所可转债（如 128125.SZ），与 tushare 通用 ts_code 约定（000001.SZ / 600000.SH）一脉相承；
2. 历史纵深：数据可回溯到 1998 年前后的老券（125301.SZ、125302.SZ 等），说明 cb_issue 覆盖二十余年发行记录，适合做全历史可转债发行的复盘研究；
3. 字段可能为空：125009.SZ 的 ann_date 为 None——早期或特殊券种个别字段缺失属正常现象，下游处理时应对缺失值做好容忍与清洗（例如 pd.to_numeric(errors='coerce') 后再做数值计算）。

七、实战联动：把发行数据接入可转债投研管线

单看发行数据价值有限，真正有用的是把 cb_issue 与债券专题下其它可转债接口串成一条**"发行 → 基本信息 → 行情 → 条款事件"**的完整数据链：

阶段	接口	对应文档	典型用途
发行	cb_issue	可转债发行	跟踪新券发行公告、申购中签、配售比例、发行规模
基础信息	cb_basic	可转债基础信息	以 ts_code 关联正股代码、转股价、期限、评级、条款
行情	cb_daily	可转债行情	上市后日线行情、纯债价值/转股价值/双溢价率
条款事件	cb_call	可转债赎回信息	强赎/到期赎回公告跟踪

典型接法：用 cb_issue 得到新发行 ts_code 列表 → 用 cb_basic 补齐正股与条款（转股价、下修/强赎/回售条款）→ 上市后用 cb_daily 跟踪估值（bond_value 纯债价值、cb_value 转股价值、cb_over_rate 转股溢价率）→ 用 cb_call 监控强赎风险。这与仓库内 agent/src/skills/convertible-bond/SKILL.md 定义的可转债三维估值（债底/股性/期权）+ 条款博弈 + 双低策略框架天然衔接——该技能文档明确写道"可转债数据需通过 tushare 的可转债接口获取，OHLCV 数据可用标准接口"，cb_issue 正是其中"发行/规模"维度的数据底座。例如做"双低策略"（双低值 = 转债价格 + 转股溢价率 × 100）时，可用 cb_issue.issue_size 过滤小规模新券，用 cb_daily.cb_over_rate 计算溢价率，再用 cb_basic 的评级与剩余期限字段完成"评级 ≥ AA-、剩余期限 > 1 年"等风控筛选。

八、注意事项与限制

1. 积分门槛：2000 积分是调用 cb_issue 的下限；5000 积分以上可获得相对较高的请求频次。积分不足时接口会返回权限类错误，属于 Tushare 服务端的正常限制。
2. 单次 2000 条上限：单次调用最多返回 2000 行，全量提取必须按日期窗口分页循环，切不可一次拉取全部历史。
3. 单位差异：plan_issue_size / issue_size 单位为元，而网上/配售/网下各渠道的 *_size 单位为张，混用前务必统一量纲。
4. 网络环境：tushare 数据源在 Vibe-Trading 的 data-routing 路由表（agent/src/skills/data-routing/SKILL.md）中被标注为 China network，非中国网络环境下可能存在访问问题；此时可考虑按路由表降级到 akshare 等替代源获取可转债数据。
5. 缺失值：早期券种个别字段（如示例中的 ann_date）可能为空，下游计算前需清洗。
6. 数据用途：Tushare 债券类数据来源于公开披露渠道，文档建议仅供个人与机构研究使用，不要用于数据商业目的（可转债赎回信息接口 cb_call 的文档中亦有同样声明，可作为该类接口的通用约束参考）。

通过以上内容，你已完整掌握 cb_issue 的权限、参数、字段、调用与联动用法，可以开始在 Vibe-Trading 中搭建属于自己的可转债发行跟踪与投研数据管线了。