tushare-data

tushare-data

Turn natural-language financial data requests into executable Tushare data workflows.

This is a natural-language-oriented financial data research skill.

What this skill is for

Typical scenarios for using this skill:

• Look at the recent trend of a stock, index, or ETF
• Check company basic information, valuation, and financial trends
• Do horizontal comparison of multiple targets
• Look at capital flows, northbound capital, the dragon-tiger list, and sector strength
• Organize announcements, news, research reports, and policy clues
• View macroeconomic data such as CPI / PPI / PMI / social financing / interest rates
• Export CSV / parquet for subsequent analysis or backtesting
• Generate a concise research summary instead of only outputting a raw field table

First understand what problem the user wants to solve, then choose interfaces, retrieve data, organize, explain, and deliver.

---

When to use

When the user expresses the following intentions, prioritize using this skill:

Market / trend

• See how XX has been doing recently
• How much has XX risen during this period
• How has performance been so far this year
• Has there been any volume increase recently
• Has this stock been strong recently

Financials / valuation / company quality

• Check XX's financial report
• Profit trend in recent quarters
• How is the financial quality
• Is cash flow good
• Is the current valuation considered high
• Help me look at PE / PB / ROE / gross margin

Comparison / ranking / screening

• Which is stronger, XX or YY
• Help me make a horizontal comparison
• Which companies have faster profit growth
• Help me screen for high ROE and low debt
• Give me a top ten ranking

Sectors / indices / themes

• Which sector has been strongest recently
• How have semiconductors been recently
• Why are robotics rising
• What are the constituent stocks of the index
• Which themes are hottest

Capital flows / sentiment

• What has capital been buying recently
• Where has northbound capital been flowing recently
• Which sector is attracting the most capital
• Who has the largest main-force capital inflow
• What are the highlights on the dragon-tiger list

Announcements / news / research reports / policy

• What announcements have there been recently
• Help me sort through XX's announcements
• Have there been any catalysts recently
• How is the news side recently
• What important policies have there been recently

Macro / cross-market

• How is the macroeconomic environment recently
• How should we view CPI / PMI recently
• What is the current market style leaning toward
• Is the broader market environment bullish or bearish
• How have Hong Kong stocks / US stocks / US Treasuries been recently

Data export / research preparation

• Export a market data file for me
• Pull the past two years of daily bars into CSV
• Generate a backtestable data table
• Pull a research table for subsequent analysis

---

What this skill is NOT for

This skill is not suitable for:

• Directly give buy/sell recommendations or act as a substitute investment advisor
• Automatically place orders or execute trades
• Scenarios requiring millisecond-level real-time trading decisions
• The implementation of complex backtesting engines and portfolio optimization systems themselves (that is a separate engineering effort)
• Forcibly fabricating data without Tushare permission/credit support

If data permissions are insufficient, the interface is unavailable, or the time range is unreasonable, clearly state the limitations; do not hard-code.

---

Natural-language trigger guide

Even if the user does not mention tushare、financials、macro these terms at all, as long as the intent matches the following meanings, this skill should still be triggered.

Common colloquial triggers

• Take a look at how this stock has been doing recently
• Give me a quick study of XX
• What is the situation with that stock mentioned last time now
• Help me look at the financial report
• Which sector has been the strongest recently
• What has northbound been buying recently
• Are there any catalyst news items
• Is this company worth focusing on
• Pull a data set for me
• Export to CSV
• Help me screen a batch of stocks
• Compare these companies

Chinese natural language priority principle

When the user speaks plainly, understand the task first; do not immediately go back to interface names and field names. Give priority to interpreting:

• "Recently" as a reasonable time window
• "Financial report" as the most recent 8 quarters / most recent fiscal year
• "Strong or not" as trend + relative strength + activity level
• "Capital attention" as net inflow, active trading, Dragon-Tiger List/northbound and other available measures

If the task has multiple reasonable interpretations, then make the minimal clarification.

---

Environment check

Before actually requesting data, perform pre-checks:

1. Check whether Python is available; version requirement 3.7+
2. Check whether the tushare package is installed·
3. Check whether TUSHARE_TOKEN exists.
4. If necessary, perform a lightweight interface smoke test (such as trading calendar / basic interfaces)
5. If the user requests a high-permission interface, prompt in advance that there may be credit/permission limits

If the token is missing, directly indicate the shortest repair path, for example:

export TUSHARE_TOKEN=your_token

Do not wait until the main query fails before exposing environment problems.

---

Intent taxonomy

Identify the task type first, then decide the interface combination.

1. Quotes / Trends

Typical questions:

• How has it been trending recently
• How much has it risen this year
• Has volatility been high recently
• Has there been any volume surge recently

Commonly used interfaces:

• daily
• pro_bar
• weekly
• monthly
• stk_mins
• rt_k / rt_min(if a real-time measure is truly needed and permissions allow)
• daily_basic

2. Basic information / Instrument identification

Typical questions:

• What company / what index / what fund is this
• Is it on ChiNext / is it ST / when was it listed

Commonly used interfaces:

• stock_basic
• fund_basic
• index_basic
• stock_company
• stock_st / st

3. Financials / Company quality

Typical questions:

• Profit trend over recent quarters
• Revenue and net profit trend over recent quarters
• How is the financial quality
• How are ROE / gross margin / cash flow

Commonly used interfaces:

• income(revenue / net profit trend takes priority)
• fina_indicator(quality indicators such as ROE / gross margin / net margin supplement)
• balancesheet
• cashflow
• forecast
• express
• disclosure_date

4. Valuation / Fundamental indicators

Typical questions:

• Is the current valuation high
• Which is cheaper
• What about PE / PB / dividend yield

Commonly used interfaces:

• daily_basic
• fina_indicator

5. Capital flow / market behavior

Typical questions:

• What has Northbound been buying recently
• Main capital flow direction
• Dragon and Tiger List situation

Commonly used interfaces:

• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• top_inst
• moneyflow_ind_dc
• moneyflow_mkt_dc

6. Sectors / indices / themes

Typical questions:

• Which sector has been strongest recently
• How is industry rotation
• What constituent stocks does a certain sector have

Commonly used interfaces:

• index_basic
• index_daily
• index_classify
• index_member_all
• sw_daily
• ths_index
• ths_member
• dc_index
• dc_member

7. Limit-up trading / sentiment / activity

Typical questions:

• Today's limit-up ladder
• Consecutive limit-up structure
• Failed limit-up rate / sentiment strength

Commonly used interfaces:

• limit_list_d
• limit_step
• kpl_list
• dc_hot
• ths_hot

8. Announcements / news / research reports / policy

Typical questions:

• What announcements or catalysts have there been recently
• What research reports have there been recently
• What has happened recently on the policy front

Commonly used interfaces:

• anns_d
• news
• major_news
• research_report
• npr
• irm_qa_sh
• irm_qa_sz

9. Macro / cross-market

Typical questions:

• CPI / PMI / social financing / M2
• Interest rates and yield curve
• Hong Kong stocks / US stocks / US Treasury data

Commonly used interfaces:

• cn_cpi
• cn_ppi
• cn_pmi
• cn_gdp
• cn_m
• sf_month
• shibor
• shibor_lpr
• us_tycr
• us_daily
• hk_daily
• index_global

10. Export / research preparation

Typical questions:

• Export market data for a certain instrument over a period
• Generate data tables for backtesting
• Output CSV / parquet

Commonly used interfaces:

• Depends on the upstream task; the core is unified output rules and naming conventions

---

Entity resolution rules

Instrument resolution

• Prioritize identifying stock names, stock codes, index names, ETF names, and fund names
• For Chinese abbreviations, first try to match the standard object
• If there are duplicate names or multiple interpretations, list the candidates and do minimal clarification
• Security codes are internally unified into a standard format, such as:600519.SH、000001.SZ

Market identification

• By default, understand it as A-shares first, unless the user explicitly mentions Hong Kong stocks / US stocks / funds / bonds / futures
• Indices, ETFs, and individual stocks must be judged separately; do not mix interfaces

Default time values

If the user does not explicitly give a time range, use reasonable defaults:

• "Recent trend" → default to the last 20 trading days
• "This period / recently" → default to the last 3 months
• "Financial reports / performance" → default to the last 8 quarters + the most recent annual period
• "How has capital flow been recently" → default to the last 5–20 trading days, adjusted according to task granularity
• "How has macro been recently" → default to the last 6–12 periods

Default sector classification

If the user only says "sector / industry / concept" but does not specify a classification system:

• For industries, prioritize relatively stable classifications such as Shenwan / CITIC
• For concepts, prioritize thematic classifications such as Tonghuashun / East Money
• If the conclusion depends on differences in specific classifications, clearly state which classification was used

---

Input normalization rules

Normalize before requesting data:

• Dates are unified as YYYYMMDD
• Check start_date <= end_date
• When the user inputs a future date, automatically trim it to the nearest available date and notify
• Bare codes such as 000001 Do not guess blindly. If it can be completed, explain the completion rule; if it cannot be completed, clarify.
• For conflicting parameters (such as trade_date and start_date/end_date given at the same time), adjudicate first; do not pass them through arbitrarily.

---

Data retrieval rules

Documentation first

Before writing request code, first confirm:

• Whether the interface name is correct
• Required parameters
• Optional parameters
• Return fields
• Quota / rate limits

Do not write field names from memory alone.

Field confirmation

For fields parameters, prioritize using a whitelist of known fields or interface documentation for confirmation. If the user requests a field that does not exist, state this clearly instead of probing blindly.

Default to segmented fetching

Do not fetch long-interval data all at once. Recommended:

• Daily / weekly / monthly bars: slice by year or quarter
• Financial reports: slice by year / reporting period
• Minute data: slice by month / week
• Large batches of multiple symbols: batch by symbol + segment by date

Retries and rate limiting

• Only perform limited retries for transient errors (network jitter, timeouts, 429)
• Do not blindly retry parameter errors, insufficient permissions, or field errors
• Add throttling during batch fetching to avoid hitting rate limits at high frequency

Segment merging

After segmented fetching:

• Merge
• Deduplicate
• Sort by primary key
• Record failed segments
• If partially successful, clearly tell the user which segments failed

---

Output contract

Unless the user explicitly wants only the raw table, prioritize output in this structure:

1. One-sentence conclusion
2. Data range and methodology
3. Key metrics / key tables
4. Anomalies / risk points / interpretation limitations
5. If there is local output, provide the file path

Result delivery format

Choose according to task complexity:

• Small results: Markdown summary + short table
• Medium data tables: CSV
• Large-scale / follow-up analysis: Parquet
• If a reusable workflow is needed: attach a Python script
• If visualization is needed: output a chart PNG or explain what chart can be drawn

Metadata

When generating data files, try to also record:

• Interface name
• Request parameters
• Fetch time
• Number of data rows
• Field list
• Whether there are failed segments / missing data

---

Workflow templates

These templates below are the core of this skill. Do not start from the interface; start from the task template.

1. Single-symbol market analysis

Applicable:

• How has XX been doing recently?
• Has this stock been strong recently?
• How has it performed year to date?

Default workflow:

1. Parse the symbol
2. Determine the time range
3. Fetch market data + necessary basic indicators
4. Summarize interval returns, trading activity, highs and lows, volatility
5. Output a one-sentence conclusion + key figures

2. Multi-symbol horizontal comparison

Applicable:

• Which is stronger, XX or YY?
• Compare these companies

Default workflow:

1. Lock the target
2. Unify the time basis
3. Select 3–5 key indicators
4. Output a comparison table
5. Provide a summary of "who is stronger in which areas"

3. Financial quality snapshot

Applicable:

• Take a look at XX's financial report
• Profit trend over the last few quarters
• How is the financial quality

Default process:

1. Pull core financial data for the last 8 quarters + the most recent fiscal year
2. Distinguish revenue, profit, gross margin, ROE, and cash flow
3. Mark points of improvement / deterioration / fluctuation
4. Explain cumulative values, single-quarter values, and year-over-year basis

4. Valuation analysis / screening

Applicable:

• Is the current valuation high
• Who is cheaper
• Screen for low valuation and high dividend yield

Default process:

1. Clarify the target pool
2. Pull daily_basic and other valuation indicators
3. Link to financial quality when necessary
4. Output rankings, extreme values, and basis explanations

5. Capital flow tracking

Applicable:

• What has capital been buying recently
• Where has northbound flow been going recently
• Who has the largest main force capital inflow

Default process:

1. Clarify the capital basis (northbound / main force / dragon-tiger list / sector capital)
2. Determine the time window
3. Pull net inflow / active trading / persistence
4. Explain in conjunction with price performance
5. Avoid describing single-day noise as a trend

6. Sector / theme rotation analysis

Applicable:

• Which sector has been strongest recently
• Where has robotics been strong recently
• What constituent stocks are in a certain concept sector

Default process:

1. Determine the classification basis
2. Pull sector interval performance
3. Link to constituent stocks, capital flow, and limit-up tiers when necessary
4. Output strong sector rankings and representative targets

7. Announcements / news / event review

Applicable:

• What announcements have there been recently
• Are there any catalysts
• How has the news landscape been recently

Default process:

1. Clarify the target and time window
2. Pull announcements / news / research reports / policy data
3. Denoise, and distill 3–5 main lines
4. Distinguish facts, announcements, and media interpretation
5. Combine with abnormal stock price movements for weak causal explanation when necessary

8. Data export and research preparation

Applicable:

• Pull a CSV
• Create a backtest data table
• Export market/financial data for a certain period

Default process:

1. Clarify the data range, frequency, and fields
2. Use a segmented strategy to fetch data
3. Clean, deduplicate, and unify field types
4. Output CSV / parquet
5. Provide the file path and metadata

9. Comprehensive research brief

Applicable:

• Give me a quick study of XX
• Make an investor-perspective brief
• First give an overall judgment

Default process:

1. One-sentence conclusion
2. Market performance
3. Financial trend
4. Valuation level
5. Fund flow situation
6. Announcements / News catalysts
7. Risk points
8. Questions worth further investigation

---

Data quality rules

After the pull is complete, at minimum perform these checks:

• schema validation
• key field existence check
• primary key deduplication
• fixed sorting
• date standardization
• numeric field type normalization

Empty result handling

An empty table is not necessarily a failure; distinguish among:

• non-trading day
• no data in the range
• stock not listed
• parameter error
• insufficient API permissions

Do not describe all empty results as "the API is broken."

---

Cache and reuse rules

To make the skill reusable long term, prioritize support for:

• Base table cache (e.g. stock_basic, trading calendar, index basic information)
• Incremental updates instead of full re-pulling each time
• Resume from breakpoints for large tasks
• Standardized naming of result files

Recommended naming format:

• daily_600519.SH_20230101_20231231_20260322.csv
• fina_indicator_300750.SZ_20260322.parquet

When there is a cache hit, it is best to indicate which data came from cache and which was newly pulled.

---

Error handling

Prefer to output errors in a layered way: "plain language + debugging details."

User-visible layer

• token not configured
• The current API may require higher points/permissions
• The time range is too large; automatically switched to segmented pulling
• The stock name is not unique; please confirm which one it is
• The current result is empty, possibly because the date is a non-trading day / the instrument is not listed / no permission

Debug layer

If necessary, add:

• API name
• parameters
• failed segment
• original exception text

Partial success principle

If some segments fail, do not say "completed successfully." State clearly:

• which parts succeeded
• which parts failed
• whether incomplete results have been generated

---

Recommended minimal interface set

Do not stuff hundreds of APIs into the main skill body. Prioritize remembering the core API set for 80% of common tasks:

• stock_basic
• trade_cal
• daily
• pro_bar
• daily_basic
• fina_indicator
• income
• balancesheet
• cashflow
• forecast
• express
• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• index_basic
• index_daily
• index_classify
• sw_daily
• ths_index
• ths_member
• limit_list_d
• limit_step
• news
• major_news
• research_report
• anns_d
• cn_cpi
• cn_pmi
• us_tycr

For all data APIs, please refer to references/数据接口.md。

---

Best practices

• Understand the task first, then choose APIs
• Fetch as little as possible; core data first, then expand
• Give conclusions first, then evidence
• By default, speak plainly; do not pile up field names
• For vague Chinese expressions such as "recent / financial report / strong or not / capital attention," there should be reasonable default interpretations
• For large tasks, give an execution plan first, then start running
• For export tasks, try to keep scripts, metadata, and file paths to facilitate reuse

---

Examples

Single-stock market data

• Look at CATL's trend over the last three months
• How much has Moutai risen so far this year
• What is roughly the maximum drawdown of China Merchants Bank over the past two years

Financials / Valuation

• Look at BYD's revenue and net profit trend over the last 8 quarters
• Is Moutai's current valuation considered high
• Help me find companies with high ROE and low debt

Comparison

• Compare the gains and valuations of Moutai, Wuliangye, and Luzhou Laojiao over the past year
• Compare the performance this year of CSI 300, CSI 500, and ChiNext

Fund flows / Sectors

• Which stocks had the largest northbound capital inflows today?
• Which sector has been the strongest recently?
• Has the semiconductor sector been strong over the past month?

Announcements / Events

• Help me sort through Cambricon's recent important announcements
• What news-driven catalysts have there been in the robotics sector recently?

Macro

• Take a look at recent changes in CPI, PPI, and PMI
• Is the current market style tilted toward growth or value?

Export

• Export the daily candlesticks of CSI 300 constituent stocks over the past two years to CSV
• Download CATL's adjusted price data from 2020 to now
• Pull ROE, PE, PB, and revenue growth over the past 3 years into a table

---

Quick rule

When the user is saying:

• Look at the trend
• Check financial reports
• Compare companies
• Look at sectors
• Look at capital flows
• Sort through announcements and news
• Look at macro
• Pull data and export

Don't first think about "which APIs there are". First think: What task is this? Which data workflow should it follow by default? How should the result be delivered to actually be useful?