tvscreener

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tvscreener

Use this skill for market queries with simple scripts first, then native Python when needed.

建议先使用简单脚本进行市场查询，必要时再使用原生Python代码。

Install

安装

bash

python3 -m pip install -U tvscreener

Python must be

>=3.10

bash

python3 -m pip install -U tvscreener

Python版本需≥3.10。

Quick commands (run from skill root)

快速命令（从技能根目录运行）

Use Python 3.10+ in your preferred environment (venv/pyenv/system Python).

bash

undefined

在你偏好的环境（venv/pyenv/系统Python）中使用Python 3.10+版本。

bash

undefined

Preset single-symbol output (recommended)

预设单标的输出（推荐使用）

python3 scripts/query_symbol.py --symbol HKEX:700 --market HONGKONG

Custom query (fields + filters)

自定义查询（字段+筛选条件）

bash scripts/run_query.sh
--market CHINA
--symbol SHSE:600519
--fields 'NAME,PRICE,CHANGE_PERCENT,VOLUME,RELATIVE_STRENGTH_INDEX_14,MACD_LEVEL_12_26,MACD_SIGNAL_12_26,MACD_HIST,SIMPLE_MOVING_AVERAGE_20,SIMPLE_MOVING_AVERAGE_50,SIMPLE_MOVING_AVERAGE_200,EXPONENTIAL_MOVING_AVERAGE_20,EXPONENTIAL_MOVING_AVERAGE_50,EXPONENTIAL_MOVING_AVERAGE_200,BOLLINGER_UPPER_BAND_20,BOLLINGER_LOWER_BAND_20,STOCHASTIC_PERCENTK_14_3_3,STOCHASTIC_PERCENTD_14_3_3,AVERAGE_TRUE_RANGE_14,MOVING_AVERAGES_RATING'
--filter 'NAME=600519'

Field discovery

字段发现

python3 scripts/discover_fields.py --keyword macd --limit 20

undefined

python3 scripts/discover_fields.py --keyword macd --limit 20

undefined

Shell quoting notes

Shell引号使用说明

Wrap
```
--fields
```
and
```
--filter
```
in single quotes.
If you use interval syntax like
```
FIELD|60
```
, quoting is mandatory to avoid shell pipe parsing.

请将
```
--fields
```
和
```
--filter
```
参数用单引号包裹。
如果你使用类似
```
FIELD|60
```
的区间语法，必须添加引号，避免被Shell解析为管道命令。

Query rules

查询规则

Core technical set (recommended):

PRICE

CHANGE_PERCENT

VOLUME

RELATIVE_STRENGTH_INDEX_14

MACD_LEVEL_12_26

MACD_SIGNAL_12_26

MACD_HIST

SIMPLE_MOVING_AVERAGE_20/50/200

EXPONENTIAL_MOVING_AVERAGE_20/50/200

BOLLINGER_UPPER_BAND_20

BOLLINGER_LOWER_BAND_20

STOCHASTIC_PERCENTK_14_3_3

STOCHASTIC_PERCENTD_14_3_3

AVERAGE_TRUE_RANGE_14

MOVING_AVERAGES_RATING

Interval fields syntax:
```
FIELD|60
```
/
```
FIELD|240
```
(example:
```
RELATIVE_STRENGTH_INDEX_14|60
```
)
- Current caveat: interval fields may fail in
```
scripts/custom_query.py
```
  with
```
FieldWithInterval
```
  attribute errors in some tvscreener versions.
- Workaround: run without interval fields, or use
```
scripts/query_symbol.py
```
  for stable single-symbol technical snapshots.
Filters:
```
=
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
>=
```
,
```
<=
```

推荐核心技术指标集合：

PRICE

CHANGE_PERCENT

VOLUME

RELATIVE_STRENGTH_INDEX_14

MACD_LEVEL_12_26

MACD_SIGNAL_12_26

MACD_HIST

SIMPLE_MOVING_AVERAGE_20/50/200

EXPONENTIAL_MOVING_AVERAGE_20/50/200

BOLLINGER_UPPER_BAND_20

BOLLINGER_LOWER_BAND_20

STOCHASTIC_PERCENTK_14_3_3

STOCHASTIC_PERCENTD_14_3_3

AVERAGE_TRUE_RANGE_14

MOVING_AVERAGES_RATING

带区间的字段语法：
```
FIELD|60
```
/
```
FIELD|240
```
（示例：
```
RELATIVE_STRENGTH_INDEX_14|60
```
）
- 当前注意事项：在部分tvscreener版本中，使用
```
scripts/custom_query.py
```
  时，带区间的字段可能会触发
```
FieldWithInterval
```
  属性错误。
- 解决方法：不使用带区间的字段，或使用
```
scripts/query_symbol.py
```
  获取稳定的单标的技术指标快照。
筛选条件支持：
```
=
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
>=
```
,
```
<=
```

Troubleshooting

问题排查

```
ImportError: cannot import name 'Market' from 'tvscreener'
```
- Usually caused by mismatched Python/site-packages or multiple Python environments.
- Fix: ensure commands and installation use the same Python (3.10+), then reinstall:
  - ```
  python3 -m pip install -U tvscreener
```
```
zsh: command not found: 60,...
```
- Cause: unquoted
```
FIELD|60
```
  interpreted as shell pipes.
- Fix: single-quote the full
```
--fields
```
  string.

```
ImportError: cannot import name 'Market' from 'tvscreener'
```
- 通常是由于Python/site-packages版本不匹配或存在多个Python环境导致。
- 修复方法：确保命令和安装使用同一版本的Python（3.10+），然后重新安装：
  - ```
  python3 -m pip install -U tvscreener
```
```
zsh: command not found: 60,...
```
- 原因：未加引号的
```
FIELD|60
```
  被Shell解析为管道命令。
- 修复方法：将整个
```
--fields
```
  字符串用单引号包裹。

References

参考资料

Workflow + patterns:
```
references/README_USAGE.md
```

API details:

```
references/api/screeners.md
```
```
references/api/fields.md
```
```
references/api/filters.md
```
```
references/api/enums.md
```

If scripts are insufficient, read references and write direct Python using tvscreener native API.

工作流及模式：
```
references/README_USAGE.md
```

API详情：

```
references/api/screeners.md
```
```
references/api/fields.md
```
```
references/api/filters.md
```
```
references/api/enums.md
```

如果脚本无法满足需求，请阅读参考资料并使用tvscreener原生API编写直接的Python代码。

Regression test

回归测试

bash

bash scripts/test_markets.sh

Covers Tencent (HK), Moutai (A), A-share ETF (510300), and BIDU (US).

bash

bash scripts/test_markets.sh

测试覆盖腾讯（港股）、茅台（A股）、A股ETF（510300）及百度（美股）。