
Openclaw Data China Stock
- 268 installs
- 50 repo stars
- Updated May 5, 2026
- shaoxing-xie/openclaw-data-china-stock
openclaw-data-china-stock is an agent skill that collects unified A-share, ETF, and option market data for OpenClaw agents.
About
openclaw-data-china-stock is an OpenClaw data-collection skill that exposes agent-callable tools for Chinese A-share, ETF, and listed-option markets. Solo and indie builders wiring quant or macro workflows in OpenClaw use it as the unified fetch layer instead of hand-rolling exchange-specific scrapers. The recommended path is `tool_fetch_market_data`, with compatibility aliases for index, ETF, and option series and contract lookup by underlying. When caching is on, read tools load prior Parquet snapshots so agents do not repeat paid or rate-limited pulls. The repo documents a paired analyst suite—macro, technical, scanner, sentinel, fund-flow, strategy backtester MVP, and fundamental skills—so this skill typically sits upstream of those analyzers. Complexity is intermediate: you need OpenClaw plugin conventions, API credentials where providers require them, and discipline about not shipping local data or venv artifacts. Use it whenever Validate or Grow work needs repeatable China market snapshots inside an agent session.
- `tool_fetch_market_data` as the recommended cross-asset unified entry
- Dedicated fetch aliases for index, ETF, and option data plus `tool_get_option_contracts` by underlying
- Read tools for cached Parquet when local persistence is enabled
- OpenClaw/ClawHub-compatible toolset with packaging ignores for data, logs, and local DB artifacts
- Pairs with a 7-skill suite (macro, technical, scanner, sentinel, fund-flow, backtester MVP, fundamental)
Openclaw Data China Stock by the numbers
- 268 all-time installs (skills.sh)
- +16 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #348 of 1,106 Finance & Trading skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/shaoxing-xie/openclaw-data-china-stock --skill openclaw-data-china-stockAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 268 |
|---|---|
| repo stars | ★ 50 |
| Security audit | 0 / 3 scanners passed |
| Last updated | May 5, 2026 |
| Repository | shaoxing-xie/openclaw-data-china-stock ↗ |
What it does
Install this when your OpenClaw agent needs unified A-share, ETF, and listed-option market data fetch and optional Parquet cache reads for China markets.
Who is it for?
OpenClaw users prototyping or running China equity, ETF, and option research stacks with cached reads enabled.
Skip if: Skip if you're outside OpenClaw and only need a one-off curl to a public API without agent tool integration or local cache governance.
When should I use this skill?
OpenClaw workflows need cross-asset China market fetch or cached Parquet reads before macro, technical, or scanner skills run.
What you get
Your agent calls a single fetch surface (plus optional Parquet reads) so downstream paired analyst skills can run on normalized market snapshots.
- Fetched market datasets returned to the agent session
- Optional local Parquet or DB cache reads when persistence is enabled
By the numbers
- Documents 7 paired analyst skills in the suite (macro, technical, scanner, sentinel, fund-flow, backtester MVP, fundamen
- Exposes unified fetch plus index/ETF/option alias tools and contract lookup by underlying
Files
OpenClaw Data China Stock
This plugin provides a ClawHub/OpenClaw compatible toolset for collecting A-share, ETF, and listed option data.
Key tools
tool_fetch_market_data: Cross-asset unified entry (recommended).tool_fetch_index_data/tool_fetch_etf_data/tool_fetch_option_data: Compatibility/alias unified entries.tool_get_option_contracts: Fetch option contracts by underlying.tool_read_market_data/tool_read_*: Read previously cached Parquet data (when enabled).
Paired skill suite
skills/china-macro-analyst/SKILL.mdskills/technical-analyst/SKILL.mdskills/market-scanner/SKILL.mdskills/market-sentinel/SKILL.mdskills/fund-flow-analyst/SKILL.mdskills/strategy-backtester/SKILL.md(MVP mode)skills/fundamental-analyst/SKILL.md
China macro analyst tools
- Primary:
tool_fetch_macro_data/tool_fetch_macro_snapshot - Compatibility wrappers:
tool_fetch_macro_*(21 tools; kept for backward compatibility) - Skill:
skills/china-macro-analyst/SKILL.md(institutional 4-section narrative template; rules inmacro_config.yaml)
Multi-factor equity screening (A-share)
- `tool_screen_equity_factors`: Single entry for oscillation/trend templates (e.g.
reversal_5d,fund_flow_3d,sector_momentum_5d) overhs300|zz500|zz1000|a_share|custom; returnsquality_score,degraded,config_hash, optionalsw_mappingstats. Implemented inplugins/analysis/equity_factor_screening.py; registered intool_runner.py/config/tools_manifest.yaml(+ JSON). JSON Schema:docs/schemas/tool_screen_equity_factors.schema.json. - `tool_batch_fetch`: Batch runner includes
tool_screen_equity_factors(seeplugins/merged/tool_batch_fetch.pywhitelist). - 申万一级映射:
config/sw_industry_level1_mapping.json,由scripts/update_sw_industry_level1_mapping.py生成(默认乐咕乐股sw_index_first_info+sw_index_third_cons;可选SW_MAP_USE_EM_SPOT=1走东财快照)。消费侧:plugins/analysis/sw_industry_mapping.py。
助手侧夜盘落盘、质量门禁与熔断工具(tool_finalize_screening_nightly / tool_set_screening_emergency_pause)在 etf-options-ai-assistant 仓库注册;规程 Skill `ota_equity_factor_screening_brief` 仅在该助手仓维护并同步到 Gateway。
Fund-flow tools (pick one job, do not duplicate)
- `tool_capital_flow`: Single-stock summary for workflows that need
flow_judgement/risk_flagsstyle outputs (e.g. limit-up strategies). - `tool_fetch_a_share_fund_flow`: Tabular / ranking / history for onshore A-share money flow (
query_kindselects market/sector/stock tables, big deals, main-force ranks, sector drill-down). Uses Eastmoney/Tonghuashun-style AkShare routes with an explicit attempt chain; raw data is not investment advice. - `tool_fetch_northbound_flow`: Stock Connect northbound flows (cross-border), separate from onshore A-share flow tools—keep narratives and citations distinct.
- `tool_fetch_a_share_technical_screener`: Tonghuashun-style technical stock screeners (new highs, consecutive up days, volume patterns, MA breakouts, etc.) via AkShare
stock_rank_*_ths—not the same as locally computed MACD/RSI from OHLC (usetool_stock_data_fetcher/tool_calculate_technical_indicatorsfor those).
Safety and independence
The plugin is designed to run independently (no dependency on any other repository):
- It does not inject
~/.openclaw/.env. - It supports plugin-specific cache/data paths (configured inside the plugin).
Why it helps retail users
- Unified cross-asset entry (
tool_fetch_market_data) to reduce “tool switching” friction. - Multi-source provider priority + automatic fallback to avoid single-provider outages breaking your workflow.
- Default read-only disk cache semantics (
data_cache.enabled=false) to minimize local data pollution risk.
Typical usage
Example: fetch A-share index daily historical data:
tools:
- name: tool_fetch_market_data
params:
asset_type: index
view: historical
asset_code: "000001"
period: daily
start_date: "20260201"
end_date: "20260228"Example: fetch ETF 5-minute bars:
tools:
- name: tool_fetch_market_data
params:
asset_type: etf
view: minute
asset_code: "510300"
period: "5"
start_date: "20260201"
end_date: "20260228"Example: fetch latest CPI and use macro snapshot:
tools:
- name: tool_fetch_macro_data
params:
dataset: cpi
latest_only: true
- name: tool_fetch_macro_snapshot
params:
scope: monthly
include_quadrant: trueCache policy
- Default:
data_cache.enabled=false - Disk parquet reads are allowed (if cache exists).
- Disk parquet writes are skipped.
- Corrupted parquet files are not deleted in this mode.
data_cache.enabled=true- Disk parquet reads and writes are both enabled.
# Ignore local artifacts & caches during ClawHub packaging
data/
logs/
# Cursor / local code graph artifacts (must never ship)
.code-review-graph/
.code-review-graphignore
# Disk caches / artifacts (parquet/jsonl/sql)
*.parquet
*.jsonl
*.db
*.sqlite3
# Python environments
.venv/
venv/
__pycache__/
*.pyc
*.pyo
*.pyd
.pytest_cache/
# Node
node_modules/
# Editor / OS
.DS_Store
.idea/
.vscode/
# Large local reports / release artifacts
tool_test_report*.json
*.tgz
__pycache__/
.pytest_cache/
.venv/
node_modules/
logs/
data/
name: Unit Tests
on:
push:
pull_request:
jobs:
unittest:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
- name: Run tests
run: |
python -m unittest discover -s tests -p 'test_*.py'
- name: Optional tool-report regression (needs tool_test_report_baseline.json)
run: |
if [ -f tool_test_report_baseline.json ]; then
python scripts/test_all_tools.py --limit 35 --disable-network --report /tmp/tool_report_current.json || true
python scripts/compare_tool_reports.py tool_test_report_baseline.json /tmp/tool_report_current.json
else
echo "No tool_test_report_baseline.json; skip report comparison."
fi
data/
logs/
# Local caches / artifacts
# Full-tool smoke output (scripts/test_all_tools.py) — 体积大、随环境变化,不纳入版本库
tool_test_report*.json
*.tgz
*.parquet
*.jsonl
*.db
*.sqlite3
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.venv/
venv/
# Node
node_modules/
.npmrc
# Editor / OS
.DS_Store
.idea/
.vscode/
## Exclude Python bytecode / caches
__pycache__/
*/__pycache__/
**/__pycache__/
*.pyc
*.pyo
*.pyd
**/__pycache__/**
**/*.pyc
**/*.pyo
**/*.pyd
## Exclude Python virtualenvs
.venv/
venv/
## Exclude local runtime data / caches
data/
logs/
tool_test_report*.json
**/*.parquet
**/*.jsonl
**/*.db
**/*.sqlite3
## Exclude Node artifacts (publish should be source-only here)
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
## Exclude OS/editor junk
.DS_Store
.idea/
.vscode/
Changelog
2026-05-05 (v0.5.11)
ClawHub / 构建
- 满足 ClawHub 对 TypeScript 插件的 编译产物 校验:新增
npm run build(esbuild 输出dist/index.js),package.json的main/openclaw.extensions指向dist/index.js;prepack自动构建。 - 入口在
dist/时通过PKG_ROOT解析tool_runner.py与config/tools_manifest.json,避免路径错位。 scripts/register_openclaw_dev.py:支持从助手仓 symlinkota-*-briefskills 并写入 etf workspace agentskills(OPENCLAW_ETF_OPTIONS_ASSISTANT_ROOT)。
2026-05-03 (v0.5.10)
ClawHub 发布
- 数据底座演进:实体/L4/catalog 相关工具与契约、
factor_registry、文档与测试(详见本版本git历史)。 - README:补充 L1–L4-data 分层、健康观测、
tool_runner命令行示例与docs/data_model/等索引。
2026-04-28 (v0.5.5)
Major: CNI + CSIndex daily collectors + release hygiene
- 新增双工具:
tool_fetch_cni_index_daily(AkShareindex_hist_cni)tool_fetch_csindex_index_daily(AkSharestock_zh_index_hist_csindex)- 两工具统一输出契约:
success/message/data/count/source_id/source_raw/source_stage/quality_status/degraded_reason/attempts/elapsed_ms/task_id/run_id/_meta。 - CNI 路径补充单位显式化与标准化输出:
- 原始字段:
volume_raw(万手)、amount_raw(亿元) - 标准字段:
volume(手)、amount(元) - 新增质量门禁与错误码:
INVALID_PARAM、DEPENDENCY_MISSING、UPSTREAM_ERROR、UPSTREAM_EMPTY、UPSTREAM_SCHEMA_DRIFT、NORMALIZE_FAILED。 - 更新注册与文档:
tool_runner.pyconfig/tools_manifest.{yaml,json}plugins/data_collection/{README.md,DATA_SOURCE_REGISTRY.md,DATA_SOURCE_TOOL_INVENTORY.md}plugins/data_collection/index/指数采集工具与原始接口说明.md- 新增测试与 smoke:
tests/test_fetch_cni_daily.pytests/test_fetch_csindex_daily.pyscripts/smoke_cni_csindex_daily.py- 发布包清理:
.clawhubignore排除.code-review-graph等本地开发产物,避免发布体积异常与安装失败。
2026-04-19 (v0.5.3)
Major: market-sentinel skill (sentiment aggregate)
- 新增 Skill
skills/market-sentinel:并行聚合tool_fetch_limit_up_stocks、tool_fetch_a_share_fund_flow、tool_fetch_northbound_flow、tool_fetch_sector_data,输出overall_score、sentiment_stage(含震荡/混沌)、sub_scores、factor_attribution、data_completeness_ratio、action_bias、risk_counterevidence、confidence_band、degraded;禁止具体买卖点与杠杆建议。 - 配置:
skills/market-sentinel/config/market-sentinel_config.yaml(多risk_mode权重模板、dynamic_weight_adjustment、sentiment_stage_thresholds、聚合缓存 TTL)。 - 工具清单:上述四工具增加
sentinel_bundle/skill_hint元数据;scripts/register_openclaw_dev.py注册本 Skill 软链与 agent skills。 - 文档:
docs/sentiment/api_contract.md增补 Skill 聚合契约、阶段映射表、降级与insufficient_evidence形状;docs/sentiment/examples.md增补 ≥5 条典型问法与端到端说明。 - 测试:
tests/test_market_sentinel_aggregate_contract.py与夹具tests/fixtures/sentiment/market_sentinel_aggregate_*.json(契约与极端/降级场景)。
2026-04-18 (sentiment tools optimization closure)
Major: four sentiment tools finalized
- 完成四个情绪类工具优化收口并统一工程规范:
tool_fetch_limit_up_stockstool_fetch_a_share_fund_flowtool_fetch_northbound_flowtool_fetch_sector_data- 四工具统一接入响应契约与质量字段:
success/source/fallback_route/attempts/data_quality/cache_hit/error_code/explanation。 - 明确并落地硬约束:无上游且无缓存时直接失败,不生成估计值;缓存仅来自历史成功拉取结果。
Source chains and fallback policy
limit_up_pool链路定版:akshare.stock_zt_pool_em -> stock_zt_pool_previous_em -> stock_zt_pool_strong_em -> stock_zt_pool_sub_new_em -> cache。fund_flow链路定版:THS-first(stock_fund_flow_individual/concept/industry/big_deal),东财兜底改为可选且默认关闭。northbound链路定版:tushare.moneyflow_hsgt -> eastmoney.legacy_hsgt -> cache,移除stock_hsgt_fund_flow_summary_em。sector_snapshot链路定版:- industry:
ths_industry_summary -> sina.stock_sector_spot(新浪行业/行业) -> em_push2_industry -> akshare_industry_name_em -> cache - concept:
sina.stock_sector_spot(概念) -> em_concept_clist -> em_concept_jsonp -> cache
Documentation and quality gates
- 新增/完善情绪文档体系:
docs/sentiment/api_contract.md、dq_policy.md、error_codes.md、akshare_interface_inventory.md、akshare_interface_validation_report.md、sentiment_data_object_call_chains.md、examples.md。 - 更新项目主文档
README.md与采集子文档plugins/data_collection/README.md,同步四工具最终链路、硬约束和第三方接入入口。 tool_fetch_sector_data收口为链路内质量闸门执行(行业>=30、概念>=10、字段校验、null_ratio 校验),不通过即降级。
2026-04-17 (v0.5.1)
Release preparation
- 按 ClawHub 发布规范完成发布前预检:版本一致性、工作区状态与关键 Skill 测试。
- 基于 v0.5.0 技能扩展内容进行补丁发布,确保仓库提交与 ClawHub 版本对齐。
2026-04-17 (v0.5.0)
Major: paired tool + skill expansion
- 新增 5 个 Skill,完成“工具 + Skill”成对能力扩展:
skills/technical-analystskills/market-scannerskills/fund-flow-analystskills/strategy-backtester(MVP)skills/fundamental-analyst- 与既有
skills/china-macro-analyst共同形成 6 大分析方向(技术、扫描、资金、回测、基本面、宏观)。 - 新增统一规范文档:
skills/SKILL_CONTRACT.md,统一 frontmatter、章节结构、输出契约与安全规则。
Registration and manifest governance
- 升级
scripts/register_openclaw_dev.py,从单 Skill 注册扩展为 6 个 Skills 一次注册(含软链与 agent skills 绑定幂等处理)。 - 为核心工具补齐
scope/tool_group/recommended标签,提升 Skill-Tool 边界机器可识别性: - 技术分析:
tool_calculate_technical_indicators - 市场扫描:
tool_check_trading_status、tool_fetch_sector_data、tool_fetch_limit_up_stocks - 资金流分析:
tool_fetch_a_share_fund_flow、tool_fetch_northbound_flow - 基本面分析:
tool_fetch_stock_financials、tool_fetch_stock_financial_reports - 跨域底座:
tool_fetch_market_data
Tests and docs
- 新增测试:
tests/test_skill_metadata_integrity.pytests/test_skill_tool_mapping.pytests/test_skill_output_contract_smoke.py- 更新
README.md与INSTALL.md,补充 v0.5.0 单版本升级说明、6 个 Skill 导航与开发态注册说明。 - 版本统一升级到
0.5.0(package.json/openclaw.plugin.json)。
2026-04-17 (v0.4.3)
Documentation refinement
- 重构
README.md与README_EN.md为统一的信息架构(痛点、核心能力、快速开始、运行说明、测试与贡献),提高首次阅读和接入效率。 - 增补 ClawHub 安装兼容命令(带/不带
clawhub:前缀)与可点击的 GitHub Issues 链接,降低不同 CLI 版本下的安装与反馈门槛。
2026-04-17 (v0.4.2)
Critical fix: tail-session compatibility restore
- 新增
plugins/data_collection/index/fetch_global_hist_sina.py兼容模块,恢复历史导入路径plugins.data_collection.index.fetch_global_hist_sina,修复尾盘链路因模块缺失导致的工具执行失败。 - 增加全局指数符号别名与回退候选(如
^N225/^IXIC),并在历史接口失败时返回结构化失败结果,避免异常向上冒泡影响报告主流程。
2026-04-17 (v0.4.1)
Security and release hygiene
- 移除
plugins/data_collection/utils/ths_big_deal_limited.py中的动态 JS 执行路径,改为直接复用 AkShare 接口并本地限流截断,降低供应链与静态扫描风险。 - 强化
.clawhubignore,排除.pytest_cache/、tool_test_report*.json与*.tgz,减少发布包噪音与误报。
2026-04-17 (v0.4.0)
Major: China Macro Analyst integration
- 新增宏观采集模块
plugins/data_collection/macro/,提供统一入口tool_fetch_macro_data与快照入口tool_fetch_macro_snapshot。 - 新增 21 个兼容宏观工具
tool_fetch_macro_*,内部统一路由到 dataset 契约。 - 工具返回统一暴露数据质量字段:
as_of、staleness_days、data_lag_days、revision_policy、warnings。 - 新增 Skill:
skills/china-macro-analyst,采用机构化四段叙事模板并外置规则到macro_config.yaml。 - 新增第三方接入文档:
docs/macro/api_contract.md、docs/macro/error_codes.md、docs/macro/dq_policy.md与examples/macro/*.json。
Quality and tests
- 新增测试:
tests/test_macro_tools.py、tests/test_macro_skill.py。 - 保持 manifest/tool_runner 对齐,新增宏观工具后仍可通过 parity 校验。
2026-04-16
Major Upgrade: Technical Indicators Expansion
- 新增并完成
tool_calculate_technical_indicators的 P0/P1/P2 全量实现。 - 指标总数扩展至 58:
- P0: 19
- P1: 10
- P2: 29(CDL 形态识别 20 + 统计 6 + 波动补充 3)
- 引擎策略完善:
TA-Lib优先,pandas-ta自动降级,builtin最后兜底。 - 新增结构化错误码:
UPSTREAM_EMPTY_DATA。 - 完善解释器解析策略(支持环境变量优先 + 本地
.venv自动发现)。 - 文档体系升级:
README.md(产品化入口)INSTALL.md(安装部署指南)- 指标文档增加字段对照表与 P2 说明
Patch: restore full tool registration (compat)
- 将
config/tools_manifest.{json,yaml}与tool_runner.py恢复为全量工具清单,保证历史工具仍可被 OpenClaw 正常发现与执行。 - 重新加入并映射
tool_calculate_technical_indicators到新增的技术指标引擎实现,支持 P0/P1/P2(共 58 指标)。
Validation
- 指标工具、manifest/tool_runner 对齐测试全部通过。
- 真实行情 smoke 验证通过(含 P2 字段)。
# OpenClaw-data-china-stock:仅保留本仓库 tools_manifest 已注册工具及其依赖代码会读取的配置项。
# 已移除:option_contracts、signal_params、etf_trading、opening_analysis、volatility_engine、
# prediction_quality、prediction_monitoring、llm_enhancer、data_sources、tushare.prefer_minute、
# notification 中非 webhook 的大型块、system.data_storage 下未参与缓存路径的子项等(无工具引用)。
# ${VAR} 由 src/config_loader.py 在加载时解析为环境变量。
logging:
level: INFO
file_path: logs/openclaw-data-china-stock_{date}.log
max_file_size_mb: 10
backup_count: 7
# src/realtime_full_fetch_cache.py:指数/ETF 全量快照类请求的进程内短缓存
realtime_full_fetch_cache:
enabled: true
ttl_seconds: 45
# 代理策略(按数据源控制,避免全局代理污染)
network:
proxy:
default:
enabled: false
url: ""
per_source:
yfinance:
enabled: true
url: "http://127.0.0.1:2080"
fmp:
enabled: false
url: ""
sina:
enabled: false
url: ""
system:
data_storage:
data_dir: data
trading_hours:
morning_start: 09:30
morning_end: '11:30'
afternoon_start: '13:00'
afternoon_end: '15:00'
timezone: Asia/Shanghai
holidays:
2026:
- '20260101'
- '20260102'
- '20260103'
- '20260215'
- '20260216'
- '20260217'
- '20260218'
- '20260219'
- '20260220'
- '20260221'
- '20260222'
- '20260223'
- '20260404'
- '20260405'
- '20260406'
- '20260501'
- '20260502'
- '20260503'
- '20260504'
- '20260505'
- '20260619'
- '20260620'
- '20260621'
- '20260925'
- '20260926'
- '20260927'
- '20261001'
- '20261002'
- '20261003'
- '20261004'
- '20261005'
- '20261006'
- '20261007'
# src/data_cache.py:enabled=false 时不写入 parquet(仍可读已有缓存);与 SKILL/README 默认语义一致
data_cache:
enabled: false
tushare:
enabled: true
token: "${TUSHARE_TOKEN}"
# src/tushare_fallback.py stk_mins 限频;默认 true,显式写出便于查阅
enable_rate_limit: true
# 全球指数最新快照(plugins/data_collection/index/fetch_global.py);主仓 etf-options-ai-assistant 以 config/domains/market_data.yaml 为准
data_sources:
global_index:
latest:
priority:
- yfinance
- fmp
- sina
fmp:
enabled: true
api_keys:
- "${FMP_API_KEY}"
- "${FMP_API_KEY_BACKUP}"
# 因子注册表 + 多源链(catalog)。加载器:plugins.utils.plugin_data_registry.load_registry()
# 优先路径:config/factor_registry.yaml(与实施方案命名一致);旧路径 plugin_data_registry.yaml 已弃用。
schema_version: "1.0.0"
registry_note: "配置优先于代码内隐式顺序;退出条件见 docs/data_model/catalog_runtime_alignment.md、meta_contract.md 与运维文档。"
factors:
- factor_id: reversal_5d
category: momentum
source_tool: tool_screen_equity_factors
min_history_days: 6
output_unit: "%"
providers: [derived]
- factor_id: fund_flow_3d
category: flow
source_tool: tool_screen_equity_factors
min_history_days: 4
output_unit: "score"
providers: [eastmoney, ths]
- factor_id: sector_momentum_5d
category: sector
source_tool: tool_screen_equity_factors
min_history_days: 6
output_unit: "score"
providers: [akshare, sina]
- factor_id: pe_ttm
category: valuation
source_tool: tool_screen_equity_factors
implemented: false
note: "注册占位;选股引擎接入前勿从 ALLOWED 暴露"
- factor_id: pb_mrq
category: valuation
source_tool: tool_screen_equity_factors
implemented: false
note: "注册占位"
source_chains:
global_index_spot:
description: "全球指数现货;与 fetch_global_index_spot 循环源 id 一致(yfinance|fmp|sina)"
provider_tags:
- yfinance
- fmp
- sina
a_share_fund_flow:
description: "A 股主力资金流;与 _run_chain 内 (ths|eastmoney) 标签一致;cache 为占位不参排"
provider_tags:
- ths
- eastmoney
- cache
technical_indicators:
description: "技术指标引擎回退链摘要"
provider_tags:
- talib
- pandas_ta
- builtin
# 缓存预热:由 scripts/preheat_cache.py 读取;默认关闭,避免未配置 Cron 时误跑。
# Cron 建议在宿主 etf-options-ai-assistant / OpenClaw jobs.json 中以 bash -lc + set -a source ~/.openclaw/.env 调度。
preheat:
enabled: false
targets:
- name: fund_flow_sector_rank_smoke
tool: tool_fetch_a_share_fund_flow
params:
query_kind: sector_rank
provider_preference: auto
limit: 20
sector_type: industry
rank_window: immediate
options:
parallel: true
max_workers: 3
timeout_seconds: 120
version: 1
updated_at: "2026-04-30"
sectors:
- sector_name: "食品饮料"
index_code: "SWL1_FOOD_BEV"
etf_code: "512690"
etf_name: "酒ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "医药生物"
index_code: "SWL1_MED"
etf_code: "512010"
etf_name: "医药ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "电子"
index_code: "SWL1_ELECTRONICS"
etf_code: "159997"
etf_name: "电子ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "计算机"
index_code: "SWL1_COMPUTER"
etf_code: "512720"
etf_name: "计算机ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "国防军工"
index_code: "SWL1_DEFENSE"
etf_code: "512660"
etf_name: "军工ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "有色金属"
index_code: "SWL1_METALS"
etf_code: "512400"
etf_name: "有色金属ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "非银金融"
index_code: "SWL1_NONBANK_FIN"
etf_code: "512880"
etf_name: "证券ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "银行"
index_code: "SWL1_BANK"
etf_code: "512800"
etf_name: "银行ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "电力设备"
index_code: "SWL1_POWER_EQUIP"
etf_code: "516160"
etf_name: "新能源ETF"
min_liquidity: 100000000
last_verified: "2026-04-30"
- sector_name: "通信"
index_code: "SWL1_TELECOM"
etf_code: "515880"
etf_name: "通信ETF"
min_liquidity: 80000000
last_verified: "2026-04-30"
- sector_name: "传媒"
index_code: "SWL1_MEDIA"
etf_code: "512980"
etf_name: "传媒ETF"
min_liquidity: 80000000
last_verified: "2026-04-30"
- sector_name: "汽车"
index_code: "SWL1_AUTO"
etf_code: "516110"
etf_name: "汽车ETF"
min_liquidity: 80000000
last_verified: "2026-04-30"
- sector_name: "家用电器"
index_code: "SWL1_APPLIANCE"
etf_code: "159996"
etf_name: "家电ETF"
min_liquidity: 80000000
last_verified: "2026-04-30"
- sector_name: "建筑材料"
index_code: "SWL1_MATERIALS"
etf_code: "516680"
etf_name: "建材ETF"
min_liquidity: 50000000
last_verified: "2026-04-30"
- sector_name: "钢铁"
index_code: "SWL1_STEEL"
etf_code: "515210"
etf_name: "钢铁ETF"
min_liquidity: 50000000
last_verified: "2026-04-30"
- sector_name: "煤炭"
index_code: "SWL1_COAL"
etf_code: "515220"
etf_name: "煤炭ETF"
min_liquidity: 80000000
last_verified: "2026-04-30"
- sector_name: "石油石化"
index_code: "SWL1_PETRO"
etf_code: "159930"
etf_name: "能源ETF"
min_liquidity: 50000000
last_verified: "2026-04-30"
- sector_name: "房地产"
index_code: "SWL1_REAL_ESTATE"
etf_code: "512200"
etf_name: "房地产ETF"
min_liquidity: 50000000
last_verified: "2026-04-30"
- sector_name: "交通运输"
index_code: "SWL1_TRANSPORT"
etf_code: "515330"
etf_name: "交通运输ETF"
min_liquidity: 50000000
last_verified: "2026-04-30"
- sector_name: "农林牧渔"
index_code: "SWL1_AGRI"
etf_code: "159825"
etf_name: "农业ETF"
min_liquidity: 30000000
last_verified: "2026-04-30"
# Sector rotation environment gate (RPS breadth / strength).
# When enabled=false, tool returns gate=UNKNOWN with reason_codes env_gate_disabled (legacy behavior).
version: 1
updated_at: "2026-05-01"
enabled: true
# RPS(20d) threshold for counting "strong" sectors
strong_rps_threshold: 85.0
# strong_sector_ratio = count(rps20 >= strong_rps_threshold) / N_universe
go_strong_ratio_min: 0.30
caution_strong_ratio_min: 0.10
# Applied to base allocation_pct (integer round). STOP uses 0.
caution_allocation_multiplier: 0.5
stop_allocation_multiplier: 0.0
# Top-K volume confirmation (uses tool_fetch_market_data daily klines; units = plugin field)
volume_signals:
enabled: true
lookback_days: 30
surge_ratio_min: 1.2
shrink_ratio_max: 0.7
# 动态源优先级(可选):默认关闭;仅在 registry merge 层对已允许的 provider 做 tie-break。
# 分数来源:data/meta/source_health_history_rollup.json(probe 成功率序列最后一日的 success_rate)。
dynamic_priority_enabled: false
adjustment_mode: tie_break_only
tools:
- id: tool_fetch_index_realtime
label: 获取指数实时数据
description: 获取主要指数的实时行情数据(融合Coze get_index_realtime.py)。何时用:盘前/盘中快扫。
description_short: 获取指数实时行情,支持多代码逗号分隔。
parameters:
type: object
properties:
index_code:
type: string
description: 指数代码,支持逗号分隔多个,如 000001 或 000300,000001
default: '000001'
- id: tool_fetch_index_historical
label: 获取指数历史数据
description: 获取指数历史K线数据(日线/周线/月线)。
description_short: 获取指数历史K线数据(日线/周线/月线)。
parameters:
type: object
properties:
index_code:
type: string
description: 指数代码,如 000300
period:
type: string
description: daily|weekly|monthly
default: daily
start_date:
type: string
description: 开始日期 YYYYMMDD
end_date:
type: string
description: 结束日期 YYYYMMDD
required:
- index_code
- id: tool_fetch_cni_index_daily
label: 获取国证指数日频数据
description: 基于 AkShare index_hist_cni 获取指定国证/深证指数区间日频行情(标准化输出,含质量元数据)。
description_short: 国证指数日频(AkShare index_hist_cni)。
parameters:
type: object
properties:
symbol:
type: string
description: 指数代码,如 399001
start_date:
type: string
description: 开始日期 YYYYMMDD 或 YYYY-MM-DD
end_date:
type: string
description: 结束日期 YYYYMMDD 或 YYYY-MM-DD
task_id:
type: string
description: 任务标识(可选)
run_id:
type: string
description: 运行标识(可选)
required:
- symbol
- start_date
- end_date
- id: tool_fetch_csindex_index_daily
label: 获取中证指数日频数据
description: 基于 AkShare stock_zh_index_hist_csindex 获取指定中证指数区间日频行情(标准化输出,含质量元数据)。
description_short: 中证指数日频(AkShare stock_zh_index_hist_csindex)。
parameters:
type: object
properties:
symbol:
type: string
description: 指数代码,如 000300
start_date:
type: string
description: 开始日期 YYYYMMDD 或 YYYY-MM-DD
end_date:
type: string
description: 结束日期 YYYYMMDD 或 YYYY-MM-DD
task_id:
type: string
description: 任务标识(可选)
run_id:
type: string
description: 运行标识(可选)
required:
- symbol
- start_date
- end_date
- id: tool_fetch_index_minute
label: 获取指数分钟数据
description: 获取指数分钟K线数据。
description_short: 获取指数分钟K线数据。
parameters:
type: object
properties:
index_code:
type: string
description: 指数代码
period:
type: string
description: 5|15|30|60 或 5,15,30|all
default: '5'
lookback_days:
type: number
description: 回溯天数
default: 5
required:
- index_code
- id: tool_fetch_index_opening
label: 获取指数开盘数据
description: 获取指数开盘数据(9:28 集合竞价)。不维护指数白名单;支持 6 位代码或 sh/sz 前缀、逗号多代码;39 开头深证,其余上证映射(见
index_code_utils)。优先 akshare(新浪/东财),akshare 不可用时降级 mootdx quotes(开盘为近似)。
description_short: 指数开盘数据(9:28),无白名单。
parameters:
type: object
properties:
index_codes:
type: string
description: 6 位指数代码或 sh/sz 前缀,逗号多代码,如 000001,sh000300,sz399001
required: []
- id: tool_fetch_index_data
label: 获取指数数据(统一入口)
description: data_type=realtime|historical|minute|opening|global_spot(全球主要指数最新快照),内部委托 plugins.data_collection.index.*。
description_short: 指数数据统一入口(merged)。
parameters:
type: object
properties:
data_type:
type: string
description: realtime|historical|minute|opening|global_spot(全球指数最新快照)
index_code:
type: string
description: 指数代码
default: '000001'
period:
type: string
start_date:
type: string
end_date:
type: string
lookback_days:
type: number
default: 5
mode:
type: string
default: production
required:
- data_type
- id: tool_fetch_etf_data
label: 获取ETF数据(统一入口)
description: data_type=realtime|historical|minute,内部委托 plugins.data_collection.etf.*。
description_short: ETF 数据统一入口(merged)。
parameters:
type: object
properties:
data_type:
type: string
description: realtime|historical|minute
etf_code:
type: string
default: '510300'
period:
type: string
start_date:
type: string
end_date:
type: string
lookback_days:
type: number
default: 5
required:
- data_type
- id: tool_fetch_option_data
label: 获取期权数据(统一入口)
description: data_type=realtime|greeks|minute,内部委托 plugins.data_collection.option.*。
description_short: 期权数据统一入口(merged)。
parameters:
type: object
properties:
data_type:
type: string
description: realtime|greeks|minute
contract_code:
type: string
description: 期权合约代码
period:
type: string
default: '15'
required:
- data_type
- contract_code
- id: tool_fetch_etf_realtime
label: 获取ETF实时数据
description: 获取ETF实时行情数据。
description_short: 获取ETF实时行情数据。
parameters:
type: object
properties:
etf_code:
type: string
description: ETF代码,如 510300
default: '510300'
- id: tool_fetch_etf_historical
label: 获取ETF历史数据
description: 获取ETF历史K线数据。
description_short: 获取ETF历史K线数据。
parameters:
type: object
properties:
etf_code:
type: string
description: ETF代码
period:
type: string
description: 周期
default: daily
start_date:
type: string
description: 开始日期
end_date:
type: string
description: 结束日期
required:
- etf_code
- id: tool_fetch_etf_minute
label: 获取ETF分钟数据
description: 获取ETF分钟K线数据。
description_short: 获取ETF分钟K线数据。
parameters:
type: object
properties:
etf_code:
type: string
description: ETF代码
period:
type: string
description: 5|15|30|60 或 5,15,30|all
default: '5'
lookback_days:
type: number
description: 回溯天数
default: 5
required:
- etf_code
- id: tool_fetch_etf_iopv_snapshot
label: 获取 ETF IOPV/折价率
description: ETF 快照查询;主源 AkShare fund_etf_spot_ths,备源 AkShare fund_etf_category_sina(symbol=ETF基金)。
description_short: ETF 快照(同花顺主源,新浪备源)。
parameters:
type: object
properties:
etf_code:
type: string
description: ETF代码,支持逗号分隔多代码
default: '510300'
- id: tool_fetch_option_realtime
label: 获取期权实时数据
description: 获取期权实时行情数据。
description_short: 获取期权实时行情数据。
parameters:
type: object
properties:
contract_code:
type: string
description: 期权合约代码
required:
- contract_code
- id: tool_fetch_option_greeks
label: 获取期权Greeks数据
description: 获取期权的Delta、Gamma、Theta、Vega等Greeks数据。
description_short: 获取期权的Delta、Gamma、Theta、Vega等Greeks数。
parameters:
type: object
properties:
contract_code:
type: string
description: 期权合约代码
required:
- contract_code
- id: tool_fetch_option_minute
label: 获取期权分钟数据
description: 获取期权分钟K线数据。
description_short: 获取期权分钟K线数据。
parameters:
type: object
properties:
contract_code:
type: string
description: 期权合约代码
period:
type: string
description: 周期
default: '15'
required:
- contract_code
- id: tool_fetch_a50_data
label: 获取A50期指数据
description: 获取富时A50期指(期货)的实时和历史数据。
description_short: 获取富时A50期指(期货)的实时和历史数据。
parameters:
type: object
properties:
data_type:
type: string
description: realtime|historical
default: realtime
start_date:
type: string
description: 开始日期(历史数据)
end_date:
type: string
description: 结束日期(历史数据)
- id: tool_fetch_sector_data
label: 获取板块轮动数据
description: 全列表截面:行业优先 AkShare stock_board_industry_summary_ths(同花顺页),其次新浪 stock_sector_spot,再东财 push2/AkShare;概念优先新浪「概念」,再东财概念列表/JSONP。period 仅对东财概念 JSONP 有效;成功返回可含 data_source。
description_short: 板块轮动(THS/新浪优先,东财备用)。
scope: market_scanner
recommended: true
tool_group: market_structure
sentinel_bundle: true
skill_hint: market-sentinel
parameters:
type: object
properties:
sector_type:
type: string
description: industry|concept
default: industry
period:
type: string
description: today|week|month
default: today
- id: tool_get_option_contracts
label: 获取期权合约列表
description: 获取上交所 ETF 期权合约列表;返回中含 expiry_months_queried(本次请求所查询的到期月份)。
description_short: 获取期权合约信息列表(含到期月份查询列表)。
parameters:
type: object
properties:
underlying:
type: string
description: 标的物代码,如 510300
- id: tool_check_trading_status
label: 判断交易时间状态
description: '判断 A 股当前是否处于连续竞价等。返回 data.allows_intraday_continuous_wording:为 false
时(开盘前/午休/收盘后/非交易日)
禁止将指数/ETF 行情写成「已开盘、今日今开、盘中最高最低」;须遵守 data.quote_narration_rule_cn。
Agent 在写 A 股「实时/盘中」正文前**必须先调用**本工具。
'
description_short: 交易时段判断;写A股盘中表述前必调,见 quote_narration_rule_cn。
scope: market_scanner
recommended: true
tool_group: market_guardrails
parameters:
type: object
properties: {}
- id: tool_get_a_share_market_regime
label: A股市场时段细分
description: 细分A股时段(集合竞价/连续竞价/午休/收盘集合竞价/盘后/非交易日)并给出推荐模式。
description_short: 细分A股时段(集合竞价/连续竞价/午休/收盘集合竞价/盘后/非交易日…
parameters:
type: object
properties:
timezone:
type: string
description: 时区
default: Asia/Shanghai
now:
type: string
description: 用于测试的时间(可选,ISO 或 YYYY-MM-DD HH:MM:SS)
holidays:
type: array
description: 节假日列表(YYYYMMDD,可选)
- id: tool_filter_a_share_tradability
label: A股可交易性过滤
description: 对A股标的做可交易性过滤(疑似停牌/涨跌停等启发式判断)。
description_short: 对A股标的做可交易性过滤(疑似停牌/涨跌停等启发式判断)。
parameters:
type: object
properties:
stock_codes:
type: string
description: 股票代码(逗号分隔),如 600519,000001
assume_tradable_if_unknown:
type: boolean
description: 无法获取行情时是否默认可交易
default: false
required:
- stock_codes
- id: tool_read_market_data
label: 从缓存读取市场数据(统一入口)
description: data_type 或 data_types=index_daily|index_minute|etf_daily|etf_minute|option_minute|option_greeks,读本地缓存。
description_short: 缓存市场数据统一读取(merged)。
parameters:
type: object
properties:
data_type:
type: string
data_types:
type: array
items:
type: string
symbol:
type: string
contract_code:
type: string
period:
type: string
start_date:
type: string
end_date:
type: string
date:
type: string
since:
type: string
description: 起始日期下限 YYYYMMDD(与日线/分钟 start_date 取 max)
- id: tool_probe_source_health
label: 数据源健康探针(可选快照)
description: 粗粒度 import 级检查;write_snapshot=true 时写入 data/meta/source_health_snapshot.json 并记一条 JSONL。
description_short: 数据源健康快照
parameters:
type: object
properties:
source_ids:
type: string
description: 逗号分隔 source_id,默认 akshare,sina,yfinance,eastmoney,tushare
write_snapshot:
type: boolean
description: 是否落盘快照与事件
default: false
- id: tool_read_index_daily
label: 读取指数日线数据
description: 从本地缓存读取指数日线数据。
description_short: 从本地缓存读取指数日线数据。
parameters:
type: object
properties:
symbol:
type: string
description: 指数代码
start_date:
type: string
description: 开始日期
end_date:
type: string
description: 结束日期
required:
- symbol
- id: tool_read_index_minute
label: 读取指数分钟数据
description: 从本地缓存读取指数分钟数据。
description_short: 从本地缓存读取指数分钟数据。
parameters:
type: object
properties:
symbol:
type: string
description: 指数代码
period:
type: string
description: 周期
date:
type: string
description: 日期
required:
- symbol
- period
- date
- id: tool_read_etf_daily
label: 读取ETF日线数据
description: 从本地缓存读取ETF日线数据。
description_short: 从本地缓存读取ETF日线数据。
parameters:
type: object
properties:
symbol:
type: string
description: ETF代码
start_date:
type: string
description: 开始日期
end_date:
type: string
description: 结束日期
required:
- symbol
- id: tool_read_etf_minute
label: 读取ETF分钟数据
description: 从本地缓存读取ETF分钟数据。
description_short: 从本地缓存读取ETF分钟数据。
parameters:
type: object
properties:
symbol:
type: string
description: ETF代码
period:
type: string
description: 周期
date:
type: string
description: 日期
required:
- symbol
- period
- date
- id: tool_read_option_minute
label: 读取期权分钟数据
description: 从本地缓存读取期权分钟数据。
description_short: 从本地缓存读取期权分钟数据。
parameters:
type: object
properties:
contract_code:
type: string
description: 期权合约代码
period:
type: string
description: 周期
date:
type: string
description: 日期
required:
- contract_code
- period
- date
- id: tool_read_option_greeks
label: 读取期权Greeks数据
description: 从本地缓存读取期权Greeks数据。
description_short: 从本地缓存读取期权Greeks数据。
parameters:
type: object
properties:
contract_code:
type: string
description: 期权合约代码
date:
type: string
description: 日期
required:
- contract_code
- date
- id: tool_fetch_stock_financials
label: 获取A股财务指标
description: 批量获取A股个股最新财务指标(PE_TTM、PB、ROE、股息率等),供量化选股或单独查询。
description_short: 批量获取A股个股最新财务指标(PE_TTM、PB、ROE、股息率等)…
scope: fundamental_analyst
recommended: true
tool_group: primary_fundamental
parameters:
type: object
properties:
symbols:
type: string
description: 股票代码,逗号分隔或数组,如 600000,000001
lookback_report_count:
type: number
description: 保留最近几个报告期
default: 1
required:
- symbols
- id: tool_fetch_a_share_universe
label: 获取A股证券主数据
description: 沪深京 A 股代码与简称列表;优先 AkShare stock_info_a_code_name,失败降级东财全市场快照(列裁剪)。可选 max_rows 限制行数(0 表示不限制)。provider_preference=auto|standard|eastmoney 调整尝试顺序。返回含 source/fallback_route/attempt_counts。
description_short: A 股代码表 / 主数据列表。
parameters:
type: object
properties:
max_rows:
type: number
description: 最多返回行数,0 不限制(大数据量慎用)
default: 0
provider_preference:
type: string
description: auto|standard|eastmoney(em)— 多源尝试顺序
default: auto
- id: tool_fetch_stock_financial_reports
label: 获取A股财务报表
description: 按报告期的资产负债表/利润表/现金流量表。东财报告期表优先,可选新浪 stock_financial_report_sina 降级。statement_type=balance|income|cashflow。provider_preference=auto|eastmoney|sina。
description_short: 三大财务报表(报告期)。
scope: fundamental_analyst
recommended: true
tool_group: primary_fundamental
parameters:
type: object
properties:
stock_code:
type: string
description: 6 位股票代码,如 600000
default: '600000'
statement_type:
type: string
description: balance|income|cashflow
default: balance
provider_preference:
type: string
description: auto|eastmoney|sina
default: auto
required:
- stock_code
- id: tool_fetch_stock_corporate_actions
label: 获取A股公司行为
description: 分红(dividend)、限售解禁(restricted_unlock)、增发管道(issuance)、配股(allotment)、回购(buyback)。部分 kind 需要 stock_code;issuance/buyback 可全市场后自行过滤。
description_short: 分红/解禁/增发/配股/回购。
parameters:
type: object
properties:
action_kind:
type: string
description: dividend|restricted_unlock|issuance|allotment|buyback
stock_code:
type: string
description: 6 位代码,部分 kind 必填
default: ''
start_date:
type: string
description: allotment 用,YYYYMMDD
default: ''
end_date:
type: string
description: allotment 用,YYYYMMDD
default: ''
required:
- action_kind
- id: tool_fetch_margin_trading
label: 获取融资融券数据
description: 两融汇总/明细/深市标的。market=sh|sz;data_kind=summary|detail|underlying_sz;detail 需 date=YYYYMMDD;沪市 summary 可用 start_date/end_date。
description_short: 融资融券(沪深)。
parameters:
type: object
properties:
market:
type: string
description: sh|sz
default: sh
data_kind:
type: string
description: summary|detail|underlying_sz
default: summary
date:
type: string
description: YYYYMMDD,深市 summary 与两市 detail
default: ''
start_date:
type: string
description: 沪市融资余额区间起
default: ''
end_date:
type: string
description: 沪市融资余额区间止
default: ''
- id: tool_fetch_block_trades
label: 获取A股大宗交易
description: 东财大宗。block_kind=sctj|mrtj|mrmx|hygtj|yybph;mrtj/mrmx 用 start_date/end_date;hygtj/yybph 用 window(如 近三月)。
description_short: 大宗交易统计与明细。
parameters:
type: object
properties:
block_kind:
type: string
description: sctj|mrtj|mrmx|hygtj|yybph
default: mrtj
start_date:
type: string
description: YYYYMMDD
default: ''
end_date:
type: string
description: YYYYMMDD
default: ''
window:
type: string
description: hygtj/yybph 时间窗,如 近三月
default: 近三月
- id: tool_fetch_stock_shareholders
label: 获取A股股东与持股
description: holder_kind=top10|top10_float|holder_count|holder_change_ths|fund_holder。户数控 holder_count 支持 cninfo 与同花顺双源,provider_preference=auto|cninfo|ths。返回 records 与路由元数据。
description_short: 十大股东/户数/基金持股等。
parameters:
type: object
properties:
stock_code:
type: string
description: 6 位代码
default: '600000'
holder_kind:
type: string
description: top10|top10_float|holder_count|holder_change_ths|fund_holder
default: top10
start_date:
type: string
description: holder_count 用,YYYYMMDD
default: '20091227'
end_date:
type: string
description: holder_count 用,YYYYMMDD
default: '20991231'
provider_preference:
type: string
description: auto|cninfo|ths(仅 holder_count 多源时生效)
default: auto
max_rows:
type: number
description: 限制返回行数,0 不限制
default: 0
required:
- stock_code
- id: tool_fetch_ipo_calendar
label: 获取新股IPO数据
description: ipo_kind=declare_em|new_list_cninfo|review_em|tutor_em|stock_detail|stock_summary。后两者需 stock_code。provider_preference 调整同源多接口顺序(预留)。
description_short: 新股申报/上市/辅导/个股IPO摘要。
parameters:
type: object
properties:
ipo_kind:
type: string
description: declare_em|new_list_cninfo|review_em|tutor_em|stock_detail|stock_summary
default: declare_em
stock_code:
type: string
description: stock_detail|stock_summary 用 6 位代码
default: '600000'
provider_preference:
type: string
default: auto
max_rows:
type: number
default: 0
required:
- ipo_kind
- id: tool_fetch_index_constituents
label: 获取指数成份股
description: 指数代码如 000300、399001。include_weight 时优先拉中证权重。多源:中证→新浪→东财 index_stock_cons。provider_preference=auto|csindex|sina|eastmoney。
description_short: 指数成分与可选权重。
parameters:
type: object
properties:
index_code:
type: string
description: 6 位指数代码,如沪深300=000300、深证成指=399001;纯数字误多打位时会自动取前 6 位
default: '000300'
include_weight:
type: boolean
description: 是否优先尝试成份权重(中证)
default: false
provider_preference:
type: string
default: auto
max_rows:
type: number
default: 0
required:
- index_code
- id: tool_fetch_stock_research_news
label: 获取个股新闻与研报
description: content_kind=news|research|main_feed(主新闻流无需有效 stock_code)。东财结构化为主。provider_preference=auto|eastmoney。
description_short: 个股新闻/研报/主新闻流。
parameters:
type: object
properties:
content_kind:
type: string
description: news|research|main_feed
default: news
stock_code:
type: string
description: news/research 用 6 位代码
default: '600000'
provider_preference:
type: string
default: auto
max_rows:
type: number
description: 最大行数
default: 200
required:
- content_kind
- id: tool_screen_equity_factors
label: 多因子选股(因子引擎)
description: >-
震荡/趋势模板下,对 hs300|zz500|zz1000|a_share|custom 股票池组合 reversal_5d、fund_flow_3d、sector_momentum_5d
等因子并输出 TopN;含 quality_score、degraded、config_hash。内部仅调用既有日线/资金流/板块工具。
description_short: 多因子选股单入口(含质量分与审计哈希)。
parameters:
type: object
properties:
universe:
type: string
description: hs300 | zz500 | zz1000 | a_share | custom
default: hs300
filters:
type: object
description: 预留硬过滤(市值、流动性等)
factors:
type: array
description: 因子 id 列表,默认三项全开
items:
type: string
neutralize:
type: array
description: industry | market_cap(数据不足时会 degraded 说明)
items:
type: string
top_n:
type: number
default: 10
regime_hint:
type: string
description: oscillation | trend(影响因子权重模板)
default: oscillation
screening_date:
type: string
description: 预留对齐日 YYYY-MM-DD
custom_symbols:
type: string
description: universe=custom 时逗号分隔六码
default: ''
max_universe_size:
type: number
description: 股票池上限(性能保护)
default: 50
lookback_calendar_days:
type: number
description: 拉取日线自然日窗
default: 40
max_concurrent_fetch:
type: number
description: 拉日线并发上限,0 表示用环境变量或默认 4
default: 0
provider_preference:
type: string
default: auto
- id: tool_fetch_stock_historical
label: 获取个股历史K线
description: 获取A股个股历史K线数据(日线/周线/月线)。
description_short: 获取A股个股历史K线数据(日线/周线/月线)。
parameters:
type: object
properties:
stock_code:
type: string
description: 股票代码
default: '600000'
period:
type: string
description: daily|weekly|monthly
default: daily
start_date:
type: string
description: 开始日期
end_date:
type: string
description: 结束日期
- id: tool_fetch_stock_minute
label: 获取个股分钟数据
description: 获取A股个股分钟K线数据。
description_short: 获取A股个股分钟K线数据。
parameters:
type: object
properties:
stock_code:
type: string
description: 股票代码
default: '600000'
period:
type: string
description: 5|15|30|60
default: '5'
start_date:
type: string
end_date:
type: string
lookback_days:
type: number
description: 回溯天数
default: 5
- id: tool_fetch_stock_realtime
label: 获取个股实时数据
description: 获取A股个股实时行情。
description_short: 获取A股个股实时行情。
parameters:
type: object
properties:
stock_code:
type: string
description: 股票代码
default: '600000'
mode:
type: string
description: production|test
default: production
- id: tool_stock_data_fetcher
label: 个股数据采集与技术指标汇总
description: 批量拉取个股 realtime/daily/minute/financials,并可选计算 MACD/RSI/BOLL/MA 等技术指标与简单分析。
description_short: 个股数据采集与技术指标汇总
parameters:
type: object
properties:
action:
type: string
enum:
- fetch
default: fetch
symbols:
type: string
description: 股票代码,逗号分隔或数组,如 000539,300895
data_types:
type: array
description: 需要获取的数据类型
items:
type: string
enum:
- realtime
- daily
- minute
- financials
- technicals
default:
- realtime
- daily
- minute
- financials
- technicals
minute_period:
type: string
description: 分钟周期,如 5,15,30
default: 5,15,30
lookback_days:
type: number
description: 回溯天数
default: 20
indicators:
type: array
description: 技术指标列表
items:
type: string
default:
- ma
- macd
- rsi
- bollinger
include_analysis:
type: boolean
default: false
mode:
type: string
description: production|test
default: production
required:
- action
- symbols
- id: tool_stock_monitor
label: 个股监控与触发预警
description: 对 watchlist 执行触发器检查(price_change/volume_surge/support_break),触发后可选发送飞书通知。
description_short: 个股监控与触发预警
parameters:
type: object
properties:
action:
type: string
enum:
- start
- stop
- status
- run_once
default: run_once
watchlist:
type: array
description: 股票代码列表
items:
type: string
triggers:
type: array
description: 触发规则
items:
type: object
properties:
type:
type: string
description: price_change|volume_surge|support_break
symbol:
type: string
description: 可选,指定单只股票
pct:
type: number
description: price_change 阈值(百分比)
ratio:
type: number
description: volume_surge 阈值(倍数)
level:
type: number
description: support_break 支撑位阈值
required:
- type
output_channel:
type: string
description: feishu|dingtalk(仅返回消息)
default: feishu
cooldown_minutes:
type: number
description: 同类事件去重窗口(分钟)
default: 30
mode:
type: string
description: production|test
default: production
state_path:
type: string
description: 监控状态文件路径,可选
required:
- action
- id: tool_fetch_limit_up_stocks
label: 获取涨停股列表
description: 获取指定日或区间的涨停股列表(涨停回马枪数据源)。
description_short: 获取指定日或区间的涨停股列表(涨停回马枪数据源)。
scope: market_scanner
recommended: true
tool_group: market_sentiment
sentinel_bundle: true
skill_hint: market-sentinel
parameters:
type: object
properties:
date:
type: string
description: 单日 YYYYMMDD
start_date:
type: string
description: 区间开始 YYYYMMDD
end_date:
type: string
description: 区间结束 YYYYMMDD
exclude_st:
type: boolean
description: 是否排除ST
default: true
exclude_tail_limit_up:
type: boolean
description: 是否排除尾盘涨停
default: true
- id: tool_sector_heat_score
label: 板块热度评分
description: 计算板块热度评分(涨停回马枪用)。
description_short: 计算板块热度评分(涨停回马枪用)。
parameters:
type: object
properties:
date:
type: string
description: 日期 YYYYMMDD
limit_up_data:
type: array
description: 可选,涨停数据
sector_data:
type: object
description: 可选,板块数据
- id: tool_hotspot_discovery
label: 市场热点聚合
description: 聚合涨停、资金流、行业涨跌幅,输出当日热点TOP列表。
description_short: 聚合涨停与资金流,输出热点TOP列表。
scope: market_scanner
recommended: true
tool_group: market_sentiment
parameters:
type: object
properties:
date:
type: string
description: 指定交易日,支持 YYYYMMDD / YYYY-MM-DD
top_k:
type: number
description: 返回热点数量上限,默认 5(最大 20)
default: 5
min_heat_score:
type: number
description: 热度分阈值,低于阈值不纳入结果
default: 30
- id: tool_write_limit_up_with_sector
label: 涨停+板块日报写入
description: 拉取当日涨停、板块热度与龙头,写入 data/limit_up_research 目录。
description_short: 拉取当日涨停、板块热度与龙头,写入 data/limit_up_re…
parameters:
type: object
properties:
date:
type: string
description: 日期 YYYYMMDD
output_path:
type: string
description: 可选输出路径
- id: tool_limit_up_daily_flow
label: 涨停每日流程
description: 涨停回马枪每日流程:拉取涨停、板块热度、写JSON与报告、可选发飞书。
description_short: 涨停回马枪每日流程:拉取涨停、板块热度、写JSON与报告、可选发飞书。
parameters:
type: object
properties:
date:
type: string
description: 日期
write_json:
type: boolean
default: true
write_report:
type: boolean
default: true
send_feishu:
type: boolean
default: false
- id: tool_dragon_tiger_list
label: 龙虎榜
description: 获取龙虎榜数据(涨停回马枪相关)。
description_short: 获取龙虎榜数据(涨停回马枪相关)。
parameters:
type: object
properties:
date:
type: string
description: 交易日期 YYYYMMDD 或 YYYY-MM-DD
- id: tool_capital_flow
label: 资金流向
description: 获取个股主力/散户资金流向(capital-flow 技能入口)。
description_short: 获取个股主力/散户资金流向(capital-flow 技能入口)。
parameters:
type: object
properties:
symbols:
type: string
description: 股票列表,逗号分隔或数组
lookback_days:
type: number
description: 回溯天数
default: 3
required:
- symbols
- id: tool_fetch_northbound_flow
label: 北向资金流向
description: 获取北向资金流向数据。
description_short: 获取北向资金流向数据。
scope: fund_flow_analyst
recommended: true
tool_group: primary_fund_flow
sentinel_bundle: true
skill_hint: market-sentinel
parameters:
type: object
properties:
date:
type: string
description: 指定日期 YYYY-MM-DD
lookback_days:
type: number
description: 回溯天数
default: 1
- id: tool_fetch_a_share_fund_flow
label: A股资金流向(统一)
description: >-
A 股大盘/板块/个股资金流向(AkShare 东方财富、同花顺等多源链;原始数据非投资建议,口径以数据源页面为准)。
query_kind:market_history(大盘历史)| sector_rank(板块排名)| stock_rank(个股排名)| stock_history(单股序列)|
big_deal(大单:东财 push2 限页「大单净流入」排序快照→同花顺 HTML 限页(BIG_DEAL_THS_MAX_PAGES)→AkShare 全量;非逐笔、字段可能不同)|
main_force_rank(主力净流入排名)| sector_drill(板块成分资金流+可选历史)。
description_short: A股资金流向统一接口(东财/同花顺)。
scope: fund_flow_analyst
recommended: true
tool_group: primary_fund_flow
sentinel_bundle: true
skill_hint: market-sentinel
parameters:
type: object
properties:
query_kind:
type: string
description: >-
market_history | sector_rank | stock_rank | stock_history | big_deal | main_force_rank | sector_drill
provider_preference:
type: string
description: auto | eastmoney | ths
default: auto
limit:
type: number
description: 排名类返回条数上限(最大 200)
default: 50
max_days:
type: number
description: market_history 截取最近交易日数量
default: 120
sector_type:
type: string
description: sector_rank 用 industry | concept | region
default: industry
rank_window:
type: string
description: immediate | d3 | d5 | d10 | d20
default: immediate
stock_code:
type: string
description: stock_history 六码;可与 big_deal_stock_code 用于大单过滤
default: ""
market:
type: string
description: sh | sz,空则按代码推断
default: ""
lookback_days:
type: number
description: stock_history 回溯(上限 120)
default: 20
sector_name:
type: string
description: sector_drill 行业或概念名称(与东财列表一致)
default: ""
drill_kind:
type: string
description: sector_drill 历史接口类型 industry | concept
default: industry
include_hist:
type: boolean
description: sector_drill 是否附加行业/概念历史资金流
default: false
main_force_symbol:
type: string
description: main_force_rank 传入 stock_main_fund_flow 的 symbol(如 全部股票)
default: 全部股票
big_deal_stock_code:
type: string
description: big_deal 按六码过滤(各源列名含「代码」时生效;东财代理列为排名快照)
default: ""
required:
- query_kind
- id: tool_fetch_a_share_technical_screener
label: A股技术选股排名表
description: >-
同花顺数据中心「技术选股」排名表(AkShare stock_rank_*_ths):创新高/新低、连续涨跌、持续放量缩量、
上下突破均线、量价齐升/跌、险资举牌等。非本地 MACD/RSI 计算(请用 tool_stock_data_fetcher 或
tool_calculate_technical_indicators)。原始数据非投资建议。
description_short: A股技术选股表(同花顺 THS)。
parameters:
type: object
properties:
screener_kind:
type: string
description: >-
new_high | new_low | continuous_up | continuous_down | volume_expansion | volume_contraction |
breakout_up | breakout_down | price_volume_up | price_volume_down | insurance_holding_raise
variant:
type: string
description: >-
new_high/new_low:month | half_year | year | all_time(默认 month);breakout_up/down:ma5…ma500(默认 ma20);其余忽略
default: ""
limit:
type: number
description: 返回行数上限(最大 200)
default: 80
required:
- screener_kind
- id: tool_fetch_policy_news
label: 盘前政策要闻
description: Tavily 检索宏观/监管要闻,带本地缓存(data/cache/policy_news_*.json)。
description_short: 政策要闻 Tavily+缓存。
parameters:
type: object
properties:
max_items:
type: number
description: 条数上限
default: 5
use_cache:
type: boolean
description: 是否读缓存
default: true
disable_network:
type: boolean
description: 禁用联网
default: false
- id: tool_fetch_macro_commodities
label: 大宗商品现货涨跌
description: WTI/黄金/铜 yfinance;失败需 Tavily 降级。
description_short: 原油黄金铜 yfinance。
scope: legacy
recommended: false
tool_group: adjacent_legacy_macro
parameters:
type: object
properties:
disable_network:
type: boolean
default: false
- id: tool_fetch_overnight_futures_digest
label: A50与金龙隔夜检索摘要
description: 主源失败时定性摘要,numeric_unverified。
description_short: A50/金龙 tavily 摘要。
parameters:
type: object
properties:
disable_network:
type: boolean
default: false
- id: tool_conditional_overnight_futures_digest
label: 条件性A50金龙摘要
description: 仅当 overnight_overlay_degraded 为 true 时调用 Tavily,节省配额。
description_short: 条件性隔夜摘要。
parameters:
type: object
properties:
overnight_overlay_degraded:
type: boolean
default: false
before_open_analysis:
type: object
description: tool_analyze_before_open 的 data
disable_network:
type: boolean
default: false
- id: tool_fetch_announcement_digest
label: 重大公告速览
description: Tavily 检索 cninfo/东财等公告线索。
description_short: 公告 Tavily。
parameters:
type: object
properties:
max_items:
type: number
default: 5
disable_network:
type: boolean
default: false
- id: tool_fetch_macro_data
label: 获取宏观数据(统一入口)
description: 中国宏观数据统一入口,按 dataset 获取(PMI/CPI/PPI/M2/社融/GDP/进出口等)。
description_short: 宏观数据统一入口(推荐)。
scope: china_macro_analyst
recommended: true
tool_group: primary_macro
parameters:
type: object
properties:
dataset:
type: string
description: 数据集标识,如 pmi_official、cpi、social_financing
latest_only:
type: boolean
default: false
lookback:
type: number
default: 24
frequency:
type: string
default: monthly
required:
- dataset
- id: tool_fetch_macro_snapshot
label: 获取宏观快照
description: 组合增长/通胀/信用关键指标,输出策略解读友好的宏观快照。
description_short: 宏观快照(增长/通胀/信用)。
scope: china_macro_analyst
recommended: true
tool_group: primary_macro
parameters:
type: object
properties:
scope:
type: string
default: monthly
include_quadrant:
type: boolean
default: true
- id: tool_fetch_macro_pmi
label: 获取官方PMI
description: 获取官方制造业/非制造业 PMI 数据。
description_short: 官方 PMI。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties:
latest_only:
type: boolean
default: false
months:
type: number
default: 24
- id: tool_fetch_macro_cx_pmi
label: 获取财新制造业PMI
description: 获取财新制造业 PMI 年度序列。
description_short: 财新制造业 PMI。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_cx_services_pmi
label: 获取财新服务业PMI
description: 获取财新服务业 PMI 年度序列。
description_short: 财新服务业 PMI。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_enterprise_boom
label: 获取企业景气指数
description: 获取企业景气及企业家信心指数。
description_short: 企业景气指数。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_lpi
label: 获取物流景气指数
description: 获取物流景气指数(LPI)。
description_short: 物流景气指数。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_cpi
label: 获取CPI
description: 获取居民消费价格指数(CPI)。
description_short: 居民消费价格指数。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_ppi
label: 获取PPI
description: 获取工业品出厂价格指数(PPI)。
description_short: 工业品出厂价格指数。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_m2
label: 获取M2年率
description: 获取 M2 货币供应年率。
description_short: M2 年率。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_social_financing
label: 获取社融增量
description: 获取社会融资规模增量。
description_short: 社融增量。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_new_credit
label: 获取新增信贷
description: 获取新增人民币信贷数据。
description_short: 新增信贷。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_lpr
label: 获取LPR
description: 获取 LPR 各期限数据。
description_short: LPR 品种数据。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_fx_reserves
label: 获取外汇储备
description: 获取外汇储备年度数据。
description_short: 外汇储备。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_gdp
label: 获取GDP
description: 获取国内生产总值(GDP)相关数据。
description_short: GDP 数据。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_industrial_value
label: 获取工业增加值
description: 获取工业增加值增长数据。
description_short: 工业增加值增长。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_fixed_asset
label: 获取固定资产投资
description: 获取固定资产投资增速数据。
description_short: 固定资产投资增速。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_leverage
label: 获取宏观杠杆率
description: 获取中国宏观杠杆率数据。
description_short: 宏观杠杆率。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_exports_imports
label: 获取进出口增减
description: 获取海关进出口增减数据。
description_short: 进出口增减。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_trade_balance
label: 获取贸易帐
description: 获取美元计价贸易帐数据。
description_short: 美元贸易帐。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_exports_yoy
label: 获取出口年率
description: 获取美元计价出口年率。
description_short: 出口年率。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_unemployment
label: 获取城镇失业率
description: 获取城镇调查失业率。
description_short: 城镇调查失业率。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_macro_tax_receipts
label: 获取税收收入
description: 获取全国税收收入数据。
description_short: 全国税收收入。
scope: china_macro_analyst
recommended: false
tool_group: macro_compat
parameters:
type: object
properties: {}
- id: tool_fetch_market_data
label: 获取市场数据(跨资产统一入口)
description: Cross-asset unified entry. asset_type= index|etf|option|stock; view 含 realtime|historical|minute|opening|greeks|global_spot|iopv_snapshot;
stock 扩展 timeshare(当日分时)|pre_market(盘前)|market_overview(沪深市场总貌,可不填 asset_code)|valuation_snapshot(估值快照,委托财务指标)。
description_short: 跨资产统一入口(推荐)
scope: core_market
recommended: true
tool_group: primary_market_data
parameters:
type: object
properties:
asset_type:
type: string
description: index|etf|option|stock
default: index
asset_code:
type: string
description: index_code / etf_code / stock_code(market_overview 可选空)
default: ''
contract_code:
type: string
description: option contract_code(可选)
default: ''
view:
type: string
description: realtime|historical|minute|opening|greeks|global_spot|iopv_snapshot|timeshare|pre_market|market_overview|valuation_snapshot
default: realtime
period:
type: string
description: 个股 historical 为 daily|weekly|monthly;minute 为 1|5|15|30|60 等
start_date:
type: string
description: 历史/分钟起始日期(YYYYMMDD,可选)
end_date:
type: string
description: 历史/分钟结束日期(YYYYMMDD,可选)
lookback_days:
type: number
description: 回溯天数
default: 5
mode:
type: string
description: production|debug
default: production
required:
- asset_type
- view
- id: tool_calculate_technical_indicators
label: 计算技术指标(通用)
description: 基于历史 OHLCV 计算技术指标(P0/P1/P2 体系,P0=19/P1=10/P2=29)。默认 TA-Lib 优先、pandas-ta 自动降级,支持 append/standalone 返回模式。
scope: technical_analyst
recommended: true
tool_group: primary_technical
parameters:
type: object
properties:
asset_code:
type: string
description: 标的代码,如 510300/000300/600519
asset_type:
type: string
description: index|etf|stock
period:
type: string
default: daily
start_date:
type: string
description: YYYYMMDD,可选
end_date:
type: string
description: YYYYMMDD,可选
indicators:
type: object
description: 指标请求模型(当前实现先覆盖 P0/P1/P2;未来可扩展到 explicit/grouped)
return_mode:
type: string
description: append|standalone
default: standalone
use_cache:
type: boolean
default: true
engine_preference:
type: string
description: auto|talib|pandas_ta
default: auto
output_schema_version:
type: string
default: v1
alignment:
type: object
properties:
macd_factor:
type: number
default: 2
required:
- asset_code
- asset_type
- id: tool_fetch_sector_constituents
label: 获取行业成分股
description: 行业/概念成分股查询;优先 AkShare *_cons_em,失败可退化为指数成分近似并标记 degraded。
description_short: 行业成分股(含降级语义)。
parameters:
type: object
properties:
sector_code:
type: string
description: 行业/概念名称(或指数代码用于代理)
sector_type:
type: string
description: industry|concept
default: industry
trade_date:
type: string
description: YYYY-MM-DD
required:
- sector_code
- id: tool_calculate_sector_breadth
label: 计算行业宽度
description: 基于行业截面计算上涨占比、宽度信号,输出 L2 特征契约。
description_short: 行业宽度特征。
parameters:
type: object
properties:
sector_code:
type: string
lookback_days:
type: number
default: 20
trade_date:
type: string
required:
- sector_code
- id: tool_calculate_sector_leadership
label: 计算领涨集中度(代理版)
description: 领涨股代理法(THS 领涨股 + A股主数据映射 + 个股历史动量)输出领导力特征。
description_short: 领涨代理特征。
parameters:
type: object
properties:
sector_code:
type: string
lookback_days:
type: number
default: 60
top_k:
type: number
default: 5
weighting_scheme:
type: string
default: equal
trade_date:
type: string
required:
- sector_code
- id: tool_fetch_etf_share
label: 获取ETF份额序列
description: ETF份额时序(SSE/SZSE),输出 L1 原始契约与质量语义。
description_short: ETF份额时序。
parameters:
type: object
properties:
etf_code:
type: string
lookback_days:
type: number
default: 60
trade_date:
type: string
required:
- etf_code
- id: tool_calculate_share_trend
label: 计算ETF份额趋势
description: 基于份额序列计算 5/20/60 日变化、一致性和背离标签,输出 L2 特征契约。
description_short: 份额趋势特征。
parameters:
type: object
properties:
etf_code:
type: string
windows:
type: array
items:
type: number
trade_date:
type: string
required:
- etf_code
- id: tool_calculate_sector_momentum_v2
label: 计算行业动量v2
description: 行业涨跌幅与资金成分融合得分,输出 L2 动量增强特征。
description_short: 行业动量v2。
parameters:
type: object
properties:
sector_code:
type: string
lookback_days:
type: number
default: 20
trade_date:
type: string
required:
- sector_code
- id: tool_calculate_sector_rps
label: 计算行业ETF RPS
description: 基于行业ETF代表池,计算 RPS(20/60/120) 与窗口数据(Phase A)。
description_short: 行业ETF RPS(20/60/120)。
parameters:
type: object
properties:
lookback_days:
description: 单个窗口或窗口列表,如 20 或 [20,60,120]
default: [20, 60, 120]
etf_codes:
type: string
description: 可选,逗号分隔ETF代码;为空则使用 sector_etf_mapping 配置
default: ""
trade_date:
type: string
description: 交易日 YYYY-MM-DD(可选)
default: ""
mode:
type: string
description: production|test
default: production
- id: tool_sector_rotation_recommend
label: 行业轮动次日ETF推荐(RPS)
description: 基于 RPS(5/20)+动量(Phase A)输出 TopK 行业ETF推荐列表与因子拆解、风控提示。
description_short: 次日行业ETF推荐(Phase A)。
parameters:
type: object
properties:
top_k:
type: number
default: 5
trade_date:
type: string
description: 交易日 YYYY-MM-DD(可选)
default: ""
min_liquidity:
type: number
description: 最小成交额阈值(元)
default: 100000000
mode:
type: string
description: production|test
default: production
// index.ts
import { execFile } from "child_process";
import { promisify } from "util";
import { existsSync, readFileSync } from "fs";
import { basename, dirname, join } from "path";
import { fileURLToPath } from "url";
var execFileAsync = promisify(execFile);
var HOME = process.env.HOME || "";
var THIS_DIR = dirname(fileURLToPath(import.meta.url));
var PKG_ROOT = basename(THIS_DIR) === "dist" ? dirname(THIS_DIR) : THIS_DIR;
function getDefaultScriptPath() {
const candidate = join(PKG_ROOT, "tool_runner.py");
if (existsSync(candidate)) return candidate;
return HOME ? `${HOME}/openclaw-data-china-stock/tool_runner.py` : "";
}
function getManifestPath() {
const candidates = [
join(PKG_ROOT, "config", "tools_manifest.json"),
join(process.cwd(), "config", "tools_manifest.json")
];
for (const p of candidates) {
if (existsSync(p)) return p;
}
return candidates[0];
}
function loadToolsManifest() {
const manifestPath = process.env.OPENCLAW_DATA_CHINA_STOCK_MANIFEST_PATH || getManifestPath();
try {
const raw = readFileSync(manifestPath, "utf-8");
const data = JSON.parse(raw);
return { tools: data.tools || [] };
} catch (e) {
throw new Error(`\u52A0\u8F7D\u5DE5\u5177\u6E05\u5355\u5931\u8D25 (${manifestPath}): ${e}`);
}
}
function resolvePythonBin() {
const envPython = (process.env.OPENCLAW_DATA_CHINA_STOCK_PYTHON || "").trim();
if (envPython) {
return { bin: envPython, source: "env:OPENCLAW_DATA_CHINA_STOCK_PYTHON" };
}
const localCandidates = [
join(PKG_ROOT, ".venv", "bin", "python"),
join(PKG_ROOT, ".venv", "Scripts", "python.exe"),
join(process.cwd(), ".venv", "bin", "python"),
join(process.cwd(), ".venv", "Scripts", "python.exe")
];
for (const c of localCandidates) {
if (existsSync(c)) {
return { bin: c, source: "local-venv" };
}
}
if (HOME) {
const legacyProjectVenv = `${HOME}/openclaw-data-china-stock/.venv/bin/python`;
if (existsSync(legacyProjectVenv)) {
return { bin: legacyProjectVenv, source: "legacy-home-project-venv" };
}
const pipxMootdxPython = `${HOME}/.local/share/pipx/venvs/mootdx/bin/python`;
if (existsSync(pipxMootdxPython)) {
return { bin: pipxMootdxPython, source: "pipx-mootdx-venv" };
}
}
return { bin: "python3", source: "fallback:python3" };
}
var PYTHON_SELECTION = resolvePythonBin();
var PYTHON_BIN = PYTHON_SELECTION.bin;
var plugin = {
id: "openclaw-data-china-stock",
name: "OpenClaw Data China Stock",
description: "A\u80A1/ETF/\u671F\u6743\u6570\u636E\u91C7\u96C6\u63D2\u4EF6\uFF08\u6293\u53D6\u4E0E\u7F13\u5B58\u8BFB\u53D6\uFF09",
configSchema: {
type: "object",
properties: {
apiBaseUrl: {
type: "string",
default: "http://localhost:5000",
description: "\u53EF\u9009\u5916\u90E8\u670D\u52A1 API \u57FA\u7840\u5730\u5740\uFF08\u4EC5\u90E8\u5206\u517C\u5BB9\u63A5\u53E3\u53EF\u80FD\u9700\u8981\uFF09"
},
apiKey: { type: "string", description: "API Key\uFF08\u53EF\u9009\uFF09" },
scriptPath: {
type: "string",
description: "tool_runner.py \u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u4E0D\u586B\u5219\u7528\u9ED8\u8BA4\uFF08HOME/openclaw-data-china-stock/tool_runner.py\uFF09\u6216\u73AF\u5883\u53D8\u91CF OPENCLAW_DATA_CHINA_STOCK_SCRIPT_PATH"
},
manifestPath: {
type: "string",
description: "\u5DE5\u5177\u6E05\u5355 JSON \u8DEF\u5F84\uFF08\u53EF\u9009\uFF09\uFF0C\u4E0D\u586B\u5219\u7528 config/tools_manifest.json"
}
}
},
register(api) {
registerAllTools(api);
api.logger.info?.(`openclaw-data-china-stock: Python interpreter -> ${PYTHON_BIN} (${PYTHON_SELECTION.source})`);
api.logger.info?.("openclaw-data-china-stock: Registered all tools from manifest");
}
};
function registerAllTools(api) {
const config = api.getConfig?.() ?? {};
const scriptPath = process.env.OPENCLAW_DATA_CHINA_STOCK_SCRIPT_PATH || config.scriptPath || getDefaultScriptPath();
if (config.manifestPath) {
process.env.OPENCLAW_DATA_CHINA_STOCK_MANIFEST_PATH = config.manifestPath;
}
const { tools } = loadToolsManifest();
for (const t of tools) {
const id = t.id;
const parameters = t.parameters && typeof t.parameters === "object" && "type" in t.parameters ? t.parameters : { type: "object", properties: {} };
api.registerTool(
{
name: id,
label: t.label || id,
description: t.description || "",
parameters: {
type: parameters.type || "object",
properties: parameters.properties || {},
...Array.isArray(parameters.required) && parameters.required.length > 0 ? { required: parameters.required } : {}
},
async execute(_toolCallId, params) {
return await callPythonTool(scriptPath, id, params ?? {});
}
},
{ name: id }
);
}
}
async function callPythonTool(scriptPath, toolName, params) {
try {
const argsJson = JSON.stringify(params || {});
const { stdout, stderr } = await execFileAsync(PYTHON_BIN, [scriptPath, toolName, argsJson], {
timeout: 6e4,
maxBuffer: 10 * 1024 * 1024
});
if (stderr && !stdout) {
return { content: [{ type: "text", text: `\u9519\u8BEF: ${stderr}` }] };
}
try {
const result = JSON.parse(stdout);
return {
content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
details: result
};
} catch {
return { content: [{ type: "text", text: stdout }] };
}
} catch (err) {
const errorObj = err;
const errorMsg = errorObj instanceof Error ? errorObj.message : typeof errorObj.message === "string" ? errorObj.message : String(errorObj);
const exitCode = typeof errorObj.code !== "undefined" ? errorObj.code : void 0;
return {
content: [{ type: "text", text: `\u6267\u884C\u5931\u8D25: ${errorMsg}` }],
details: { error: errorMsg, exitCode }
};
}
}
var index_default = plugin;
export {
index_default as default
};
助手仓协同检查清单(Phase 5 / Step09)
在 etf-options-ai-assistant(或等价宿主)侧执行:
1. 去重:rg tool_l4_valuation_context|tool_l4_pe_ttm_percentile|tool_plugin_catalog_digest|tool_resolve_symbol|tool_screen_equity_factors|tool_screen_by_factors 确认无重复自算逻辑。 2. 契约:若宿主使用 data/meta/schema_registry.yaml / task_data_map.yaml,为新增插件 schema(如 valuation_context_v1、pe_ttm_percentile_band_v1、rotation_feature_aggregate_v1)补充条目与 data_layer 映射;插件侧 JSON Schema 见 openclaw-data-china-stock/docs/schemas/。 3. 发版:在开发仓发布插件后更新 ~/.openclaw/extensions/openclaw-data-china-stock(或 OpenClaw 指定安装路径),校验 openclaw.plugin.json 版本号。 4. 验收:对宿主 curl 语义层只读 API(若存在)做一次 smoke;否则以宿主 README 为准。
宿主工作区 `etf-options-ai-assistant/data/meta/` 已放置 `schema_registry.yaml`、`task_data_map.yaml`、`data_contract_version.json` 作为契约起步集;新增插件 schema 时请同步增量更新上述文件并列出发版说明。
继续遵守:不直接修改运行时 `~/.openclaw/extensions/openclaw-data-china-stock`;插件迭代在 openclaw-data-china-stock 开发仓完成后安装升级。
factor_registry(source_chains)与运行时对齐
真源与合并规则
- YAML:
config/factor_registry.yaml的source_chains为声明式顺序;与data_sources.*系统配置 并存期由代码做 安全合并,避免未在运行时实现的 tag 强行插队。 - 全球指数现货(
global_index_spot):仅识别与fetch_global_index_spot循环一致的源 id:yfinance、fmp、sina。合并逻辑见plugins.utils.plugin_data_registry.merge_global_index_spot_priority;结果写入响应source_route.active_priority与source_route.catalog_merge。 - A 股主力资金流(
a_share_fund_flow):_run_chain内(ths|eastmoney)元组在应用provider_preference之前,先按 catalog 的provider_tags重排;cache等占位 tag 被忽略。 - 技术指标引擎(
technical_indicators):engine_preference=auto(及历史遗留未知取值)时,TechnicalIndicatorEngine.select按provider_tags顺序在 已实现 的talib/pandas_ta/builtin中选第一个可用项;tool_calculate_technical_indicators的meta.catalog_engine_order反映解析后的顺序。
配置优先与回滚
- 优先:系统
data_sources.global_index.latest.priority仍决定 可用源集合;catalog 只在该集合内重排相对顺序。 - 回滚:将
source_chains.global_index_spot.provider_tags留空或删除该键 → 退化为merge_mode=config_only_empty_catalog,行为与仅读系统配置一致。 - 紧急:环境或部署层可继续用既有
data_sources覆盖;无需改代码。
退出条件(停止双轨)
- 当所有已 catalog 化路径的 合并后顺序 与 YAML 一致且连续 两个发版周期无回滚需求时,可在发版说明中宣布「系统 priority 仅作白名单/开关,顺序以 catalog 为准」,并逐步收紧系统配置中的顺序字段(仍保留 fmp 开关、密钥等)。
观测
tool_plugin_catalog_digest:只读 registry + manifest 规模摘要。tool_summarize_attempts(..., dataset_id=...):为 attempts 聚合打上 dataset 维度标签。tool_probe_source_health(..., include_catalog_digest=True):在探针结果旁附带 catalog 摘要(无网络)。
entity_id 与代码归一(L2)
过渡期策略
1. A 股交易代码:6 位数字,不带交易所前缀;由 _norm_code_6 规则归一(与 equity_factor_screening、reference_p1 一致)。 2. 指数:6 位指数码(如 000300);误粘贴超长数字时取前 6 位(与 reference_p1._norm_index_code 一致)。 3. ETF:上海常见 51****、深圳 15**** / 16**** 等;仍用 6 位作为 canonical_code,entity_type=etf。 4. 稳定 `entity_id`(可选):建议格式 stk:{code6}、idx:{code6}、etf:{code6},待 data/master_meta 补全后强制。
解析工具
tool_resolve_symbol/tool_batch_resolve_symbol:见plugins/data_collection/entity/entity_tools.py。
数据模型契约:_meta 与 data_layer
本文档为 Phase 0 单一事实源,与工具返回体中的 _meta 字段对齐。实现变更时先更新本文再改代码。
data_layer 枚举(插件侧)
| 取值 | 含义 |
|---|---|
L1_raw | 原始采集/接近上游结构 |
L2_entity | 实体解析、主数据、代码归一 |
L3_feature | 单标的因子/技术指标等标准化特征 |
L3_aggregate | 复合、无投资建议:多工具组合得分/排序/上下文,可审计 |
L3_composite | 与 L3_aggregate 二选一作为全仓统一别名(当前以 L3_aggregate 为主) |
L4_data | 确定性复合指标(分位、标签等),JSON Schema 约束;禁止 advisory |
助手侧:L3_decision / L4_decision(叙事、门闸、仓位、买卖建议)不出现在插件工具 `_meta.data_layer`。
schema_name 约定
- 复合无建议输出:
rotation_feature_aggregate_v*、*_composite_v*、*_feature_aggregate_v* - 禁止将上述输出命名为
decision_*(decision_*保留给助手侧事件 schema)
_meta 推荐字段
schema_name,schema_version,task_id,run_id,data_layergenerated_at,trade_date(如适用)source_tools/lineage_refsquality_status(与顶层quality_status一致或可说明从属关系)
entity_id(L2 扩展)
- 规范见同目录
entity_id.md(逐步补全)。 - 过渡期:工具可同时返回
canonical_code(6 位等)与可选entity_id。
多源 catalog 与运行时
- 见同目录 `catalog_runtime_alignment.md`(
factor_registry.yaml的source_chains与fetch_global/ 资金流_run_chain的合并规则、回滚与退出条件)。
P0 日志基线(§三 实证补充 · 可重复执行)
本文件落实规划 P0 日志基线:在 不修改规划正文 的前提下,为 ~/.openclaw、cron、Gateway 工具 JSON 提供 抽样方法与聚合维度,便于按 source_id / source_interface 归因。
1. 抽样位置(运行环境)
| 来源 | 路径 / 动作 | 备注 |
|---|---|---|
| OpenClaw 环境 | ~/.openclaw/.env(仅检查键是否存在,勿打印密钥) | 与 cron 预检一致:set -a; source ~/.openclaw/.env |
| Cron | ~/.openclaw/cron/jobs.json 中调用 tool_runner / openclaw-data-china-stock 的条目 | 关注 stderr 重定向文件(若配置) |
| Gateway / 工具返回 | 工具 JSON 中 success: false、`quality_status: degraded | error、message、error_code、attempts` |
2. 聚合维度(与 REGISTRY / CONNECTORS 对齐)
- 主键:
source_id(canonical)+source_interface(若存在)+error_code。 - 计数:近窗(如 7d)内失败次数、degraded 次数。
- 输出:是否需扩展全库 `error_code` 清单(参见
docs/sentiment/error_codes.md扩展思路)。
3. 实证表示例(手工或脚本填写)
| source_id(或 unknown) | source_interface(样例) | 现象(HTTP/429/空帧) | 近窗计数(占位) | 建议 error_code / 动作 |
|---|---|---|---|---|
| sina | sina.http.* | 403/502(全球指数链路等) | 待填 | UPSTREAM_FETCH_FAILED / 降频 |
| eastmoney | eastmoney.* | 限流 / 空表 | 待填 | 与附录 B 间隔叠加 |
| yfinance | yfinance.* | 代理隧道失败 | 待填 | 校验 per_source 代理 |
| tushare | tushare.* | 积分/权限与表二分钟 | 待填 | §5.1 permission_profile |
| (待抽样) |
4. 建议的一键抽样命令(在运维机执行)
# 仅示例:按任务日志路径调整
rg -n "success.: false|quality_status.: .(degraded|error)" ~/.openclaw/logs 2>/dev/null | head -200将输出粘贴到上表「现象」列或附件 issue,并在 CONNECTORS 变更说明中引用本文件日期。
Macro API Contract
Unified entry
tool_fetch_macro_data
Request:
dataset(required)latest_only(optional, defaultfalse)lookback(optional, default24)frequency(optional, defaultmonthly)
Response fields:
success: booleandata: object or nullsource: stringas_of: string or nullunit: stringdata_lag_days: number or nullstaleness_days: number or nullwarnings: string[]error: object or null
tool_fetch_macro_snapshot
Request:
scope(optional)include_quadrant(optional)
Response:
successdata.growthdata.inflationdata.creditdata.quadrant(optional placeholder; skill config should decide final mapping)
Compatibility tools
tool_fetch_macro_* wrappers remain available for backward compatibility.
Tool Scope Boundary (Important)
To reduce third-party integration ambiguity, macro-prefixed tools are split into:
- Primary (recommended):
tool_fetch_macro_datatool_fetch_macro_snapshot- China Macro Analyst compatibility wrappers (exactly 21):
tool_fetch_macro_pmitool_fetch_macro_cx_pmitool_fetch_macro_cx_services_pmitool_fetch_macro_enterprise_boomtool_fetch_macro_lpitool_fetch_macro_cpitool_fetch_macro_ppitool_fetch_macro_m2tool_fetch_macro_social_financingtool_fetch_macro_new_credittool_fetch_macro_lprtool_fetch_macro_fx_reservestool_fetch_macro_gdptool_fetch_macro_industrial_valuetool_fetch_macro_fixed_assettool_fetch_macro_leveragetool_fetch_macro_exports_importstool_fetch_macro_trade_balancetool_fetch_macro_exports_yoytool_fetch_macro_unemploymenttool_fetch_macro_tax_receipts- Adjacent legacy macro-prefixed tools (outside analyst scope):
tool_fetch_macro_commodities
Third-party users should default to Primary tools and treat wrappers as compatibility only.
Macro Data Quality Policy
Freshness
- Warn threshold:
staleness_days > 45 - Error threshold:
staleness_days > 120
Completeness
For snapshot and narrative generation, these core datasets are mandatory:
- growth:
pmi_official - inflation:
cpi(orppi) - credit:
social_financing
If any is missing, return insufficient_evidence.
Traceability
Each response should expose:
sourceas_ofrelease_time(when available)revision_policy
Macro Error Codes
| error_code | meaning | action |
|---|---|---|
VALIDATION_ERROR | request arguments invalid | fix dataset/parameter names |
UPSTREAM_TIMEOUT | upstream data source timed out | retry later, reduce scope |
UPSTREAM_FETCH_FAILED | upstream call failed after retries | inspect network and AKShare availability |
RUNTIME_ERROR | unexpected internal error | inspect traceback, raise issue |
All errors should preserve a structured payload under error.
maxConcurrentUpstream 与源链 burst
- 插件
openclaw.plugin.json→maxConcurrentUpstream:进程内上游 HTTP/AkShare 并发上限(0 表示不限制)。 - 与
config/factor_registry.yaml中source_chains协同:catalog 未来可标注「串行段」;当前以代码内节流(如upstream_spacing)为准。fetch_global_index_spot已将 catalog 与data_sources.global_index.latest.priority合并(见docs/data_model/catalog_runtime_alignment.md),source_route.catalog_merge可观测。 - 变更并发默认值时,需回归
tests/test_fetch_global_source_policy.py等与节流相关的用例。
Tool response metadata (cross-cutting contract)
This document applies to tools invoked via tool_runner.py and consumed by OpenClaw agents (including etf-options-ai-assistant).
Injected by tool_runner.py (all dict responses)
| Field | Type | Description |
|---|---|---|
elapsed_ms | int | Wall time for the tool invocation in the runner process. |
tool | string | Tool id (e.g. tool_fetch_limit_up_stocks). |
Plugin version
| Field | Type | Description |
|---|---|---|
plugin_version | string | Mirrors version in repository openclaw.plugin.json. |
Data timing and quality (tool / sentiment contract)
| Field | Type | Description |
|---|---|---|
as_of | string | Canonical generation timestamp for the payload. |
data_generated_at | string | Optional alias: when present, MUST equal as_of exactly. |
quality_score | int 0–100 | Heuristic composite; see plugins/utils/response_quality.py. |
Sentiment-specific fields remain documented in ../sentiment/api_contract.md.
P3 分批迁移说明(Router + throttle 统一)
本迭代落实 规划 P3 的「可重复模式」文档化;涨停工具链节拍已在 tool_fetch_limit_up_stocks 的 AkShare approved 链(em → previous → strong → sub_new)落地,配置键:data_sources.limit_up.upstream_chain_spacing_seconds(助手 market_data.yaml,合并进进程配置;可覆盖 OPENCLAW_LIMIT_UP_CHAIN_SPACING_SECONDS)。分钟链 / northbound 等其余域仍可按同一模式在后续 PR 分批收紧。
统一模式
1. 优先级:从 config.yaml / 助手 market_data.yaml 的 data_sources.*.priority 读取。 2. 节拍:多源 enumerate 间使用助手 data_collector._upstream_spacing_sleep(附录 B);采集任务链使用 intraday_tool_spacing_seconds。 3. 出口元数据:HTTP/SDK 成功帧经 with_source_meta;闸门类与 normalize_contract 并存时在 CONNECTORS 矩阵声明。
试点代码锚点
- 全球指数:
plugins/connectors/global_index/orchestrator.py→fetch_global.fetch_global_index_spot(契约不变)。 - Tushare 档位:
plugins/connectors/tushare/__init__.py::get_permission_profile与助手market_data.yaml的tushare.permission_profile。
Market Source 24h Regression
Planned Soak Command
python scripts/smoke_market_sources.py --mode soak --duration-hours 24 --interval-seconds 300 --output /tmp/market_soak_24h.jsonpython scripts/smoke_market_sources.py --summarize /tmp/market_soak_24h.json
Metrics To Track
elapsed_p95_msa50_cache_hit_ratioempty_value_ratio_avg- failure distribution from each run's
global.success/a50.first_success/a50.second_success
Gate
global_spot p95 < 3000ms(in-network environments with configured keys)- hot-path A50 second call keeps high
cache_hit_ratio - no silent degradation:
quality=degradedmust includedegraded_reason
Market Source Before/After
Experiment
- Command:
python scripts/smoke_market_sources.py --mode before --output /tmp/market_before.jsonpython scripts/smoke_market_sources.py --mode after --output /tmp/market_after.jsonpython scripts/smoke_market_sources.py --compare /tmp/market_before.json /tmp/market_after.json
Result Snapshot
- before elapsed:
48318ms - after elapsed:
43933ms - delta:
-4385ms - before empty ratio:
0.0 - after empty ratio:
0.0 - before a50 cache hit(second call):
true - after a50 cache hit(second call):
true
Notes
- FMP key is not configured in this environment, so global route was effectively
yfinance -> sina. - A50 second call hit cache (
cache_hit=true) withcache_age_ms=0, matching short-TTL warm-path expectation.
最终验收结论(5轮分位数)
在固定前提 set -a; source /home/xie/.openclaw/.env; set +a 下完成 5 轮测试,结果表明:
- 正确性稳定达标:
global_success_ratio=1.0,global_empty_ratio_avg=0.0 global阶段耗时稳定:p50=595ms,p95=1021ms,max=1021msindex_futures冷启动(A50首次实时链路)存在外部源波动:p50=29855ms,p95=36591ms,max=36591msindex_futures热路径(A50缓存命中)近似瞬时:p50=0ms,p95=0ms,max=0ms- A50 缓存命中稳定:
a50_source_stage_hit_ratio=1.0(source_stage=cache)
综合判断:正确性已达标,A50缓存命中稳定;性能受外部源波动影响,应以分位数持续观测,重点关注 index_futures 冷启动阶段。
备注
index_futures热路径统计出现0ms,是整数毫秒口径下的舍入结果,表示缓存命中后返回极快。
数据源封装层 — 发布与验证 Runbook(§八)
阶段一(插件)
set -a; source /home/xie/.openclaw/.env || true; set +a
cd /home/xie/openclaw-data-china-stock
./.venv/bin/python -m pytest tests/ -q --tb=no -x阶段二(助手)
set -a; source /home/xie/.openclaw/.env || true; set +a
cd /home/xie/etf-options-ai-assistant
./.venv/bin/python -m pytest tests/test_etf_rotation_core.py tests/test_rotation_data_readiness.py -q --tb=noclawhub 发布(运维执行)
在插件开发目录(需 Node + clawhub CLI + 网络):
cd /home/xie/openclaw-data-china-stock
clawhub package publish "$(pwd)" \
--family code-plugin \
--version "$(node -p "require('./package.json').version")" \
--source-repo shaoxing-xie/openclaw-data-china-stock \
--source-ref main \
--source-commit "$(git rev-parse HEAD)"安装到 ~/.openclaw/extensions/openclaw-data-china-stock 后核对 openclaw.plugin.json 与 .venv。
clawhub → openclaw plugins install 若报 missing .clawhubignore
部分 registry 校验会对 tarball 与 files[] 元数据比对;若 clawhub:@scope/name@version 安装失败并提示缺少 .clawhubignore,可在插件根目录用 与发布相同的树 打本地包并安装(等价于从已发布版本号对应的源码安装):
cd /home/xie/openclaw-data-china-stock
npm pack # 确认输出包内含 package/.clawhubignore
openclaw plugins install "$(pwd)/$(npm pack | tail -1)" --force安装器会为插件创建/更新 ~/.openclaw/extensions/openclaw-data-china-stock;Python 依赖通常使用你在 openclaw.json / 环境变量中配置的解释器(例如 OPENCLAW_DATA_CHINA_STOCK_PYTHON 指向开发仓 .venv),扩展目录内未必自带 .venv,以 openclaw plugins list / doctor 为准。
阶段三(生产)
- Gateway 抽样
tool_read_market_data/tool_fetch_index_data;cron 关键任务;GET /api/semantic/data_source_health。 - 对比升级前后
quality_status与日志量;准备版本 pin / 回滚说明。
v0.5.2 Release Notes
发布日期:2026-04-18
发布摘要
v0.5.2 完成四个情绪类工具优化收口,能力从“可调用的数据工具”升级为“统一契约、可解释、可降级、可运维”的生产级投研底座模块。
覆盖工具:
tool_fetch_limit_up_stockstool_fetch_a_share_fund_flowtool_fetch_northbound_flowtool_fetch_sector_data
核心结果
- 四工具调用链全部定版并落地:
- limit-up:
stock_zt_pool_em -> previous -> strong -> sub_new -> cache - fund-flow: THS-first(东财兜底可选且默认关闭)
- northbound:
tushare.moneyflow_hsgt -> eastmoney.legacy_hsgt -> cache - sector:
- industry:
THS -> Sina -> EM push2 -> AkShare -> cache - concept:
Sina -> EM clist -> EM jsonp -> cache - 统一响应契约与错误语义:
success/source/fallback_route/attempts/data_quality/error_code/explanation - 质量闸门机制统一接入:结构校验 + 最小样本 + 空值率阈值
- 严格执行“无估计值”原则:无上游且无缓存时直接失败
- 文档体系完整化:契约、DQ、错误码、接口清单、验证报告、调用链、示例
工具级变更概览
1) tool_fetch_limit_up_stocks
- 主口径与专项口径分离:主池、昨日涨停表现、强势池、次新池
- 情绪阶段评分模型增强:可解释打分项与阶段映射
- 接入统一缓存和质量字段
2) tool_fetch_a_share_fund_flow
- 重构为 THS-first
- 引入多查询类型一致化后处理(累计、集中度、语义字段)
- 东财兜底可选化并默认关闭
3) tool_fetch_northbound_flow
- 主源切换为
tushare.moneyflow_hsgt - 适配北向披露口径变化,强化日终趋势解释
- 移除无效 summary 路径,保留 legacy 可用降级
4) tool_fetch_sector_data
- 行业/概念链路分离并独立降级
- 行业
>=30、概念>=10的质量闸门严格执行 - 全链失败明确返回错误,不生成估计数据
配套能力与文档
- 新增共享模块:
plugins/data_collection/sentiment_common.py - 新增阶段闸门脚本:
scripts/sentiment/stage_gate_check.py - 新增接口验证脚本:
scripts/sentiment/run_akshare_interface_validation.py - 新增测试:
tests/test_sentiment_tools_contract.py - 文档索引位于
docs/sentiment/
兼容性说明
- 现有业务字段保持兼容,新增字段用于观测与诊断
- 对上层调用方建议优先读取统一字段:
successsourcefallback_routeattemptsdata_qualityerror_code/error_messageexplanation
后续计划(P2)
- 回测模块从 MVP 编排升级为独立
tool_backtest_*工具链 - 增加“情绪综合报告”聚合 Skill(串联四工具输出)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openclaw.local/schemas/pe_ttm_percentile_band_v1.json",
"title": "tool_l4_pe_ttm_percentile response",
"type": "object",
"required": ["success", "quality_status", "_meta", "data"],
"properties": {
"success": { "type": "boolean" },
"message": { "type": "string" },
"quality_status": { "type": "string", "enum": ["ok", "degraded", "error"] },
"_meta": {
"type": "object",
"required": ["schema_name", "data_layer", "task_id"],
"properties": {
"schema_name": { "const": "pe_ttm_percentile_band_v1" },
"schema_version": { "type": "string" },
"data_layer": { "const": "L4_data" },
"task_id": { "type": "string" },
"lineage_refs": { "type": "array", "items": { "type": "string" } }
}
},
"data": {
"type": "object",
"required": ["entity_id", "window_years", "sample_size", "note"],
"properties": {
"entity_id": { "type": "string" },
"window_years": { "type": "integer", "minimum": 1 },
"pe_ttm_current": { "type": ["number", "null"] },
"percentile_0_100": { "type": ["number", "null"] },
"sample_size": { "type": "integer", "minimum": 0 },
"note": { "type": "string" }
}
}
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openclaw.local/schemas/tool_screen_equity_factors.json",
"title": "tool_screen_equity_factors response (success)",
"type": "object",
"required": ["success", "quality_score", "degraded", "config_hash", "elapsed_ms", "plugin_version"],
"properties": {
"success": { "type": "boolean" },
"message": { "type": "string" },
"data": {
"type": ["array", "null"],
"items": {
"type": "object",
"required": ["symbol", "score", "factors"],
"properties": {
"symbol": { "type": "string" },
"score": { "type": "number" },
"factors": { "type": "object" },
"industry": { "type": ["string", "null"] }
}
}
},
"quality_score": { "type": "number" },
"degraded": { "type": "boolean" },
"config_hash": { "type": "string", "minLength": 8 },
"elapsed_ms": { "type": "integer", "minimum": 0 },
"plugin_version": { "type": "string" },
"universe_source": { "type": "string" },
"weights_effective": { "type": "object" },
"sw_mapping": {
"type": "object",
"properties": {
"mapping_version": { "type": ["string", "null"] },
"coverage": { "type": "number" },
"hit": { "type": "integer" },
"total": { "type": "integer" }
}
}
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://openclaw.local/schemas/valuation_context_v1.json",
"title": "tool_l4_valuation_context success payload",
"type": "object",
"required": ["success", "quality_status", "_meta", "data"],
"properties": {
"success": { "type": "boolean" },
"message": { "type": "string" },
"quality_status": { "type": "string", "enum": ["ok", "degraded", "error"] },
"_meta": {
"type": "object",
"required": ["schema_name", "data_layer", "task_id"],
"properties": {
"schema_name": { "const": "valuation_context_v1" },
"schema_version": { "type": "string" },
"data_layer": { "const": "L4_data" },
"task_id": { "type": "string" },
"lineage_refs": { "type": "array", "items": { "type": "string" } }
}
},
"data": {
"type": "object",
"required": ["entity_id", "as_of_date", "metrics", "note"],
"properties": {
"entity_id": { "type": "string" },
"as_of_date": { "type": "string" },
"metrics": { "type": "object" },
"note": { "type": "string" }
}
}
}
}
AKShare Interface Inventory (Sentiment Tools)
This inventory is the P0-0 baseline for four tools:
tool_fetch_limit_up_stockstool_fetch_a_share_fund_flowtool_fetch_northbound_flowtool_fetch_sector_data
Core interfaces (first-wave 6)
| data_object | ak_function | required_params | optional_params | key_fields | market_session_behavior | known_fail_modes |
|---|---|---|---|---|---|---|
limit_up_pool | stock_zt_pool_em | date | - | 代码, 名称, 涨跌幅, 连板数, 首封时间 | 交易日盘中/盘后可返回,非交易日可能空 | 空表、字段漂移 |
market_fund_flow | stock_market_fund_flow | - | - | 日期, 主力净流入 | 盘中刷新,盘后稳定 | 偶发断连 |
sector_fund_rank | stock_sector_fund_flow_rank | indicator, sector_type | - | 名称, 净流入, 涨跌幅 | 盘中可用,窗口受限(今日/5日/10日) | RemoteDisconnected、空表 |
stock_fund_rank | stock_individual_fund_flow_rank | indicator | - | 代码, 名称, 主力净流入 | 盘中可用,分页接口较慢 | 超时、空表 |
northbound_summary | stock_hsgt_fund_flow_summary_em | - | - | 交易日, 板块, 资金方向, 成交净买额 | 日终汇总语义更可靠 | 字段变化、空结果 |
sector_snapshot | stock_sector_spot | indicator | - | 板块, 涨跌幅 | 截面快照 | 空表、字段不全 |
Extended interfaces (P1 completion)
| data_object | ak_function | usage |
|---|---|---|
industry_board_snapshot | stock_board_industry_name_em | tool_fetch_sector_data 备用源 |
sector_flow_summary | stock_sector_fund_flow_summary | tool_fetch_a_share_fund_flow 下钻 |
sector_flow_hist | stock_sector_fund_flow_hist / stock_concept_fund_flow_hist | 历史趋势补充 |
stock_fund_history | stock_individual_fund_flow | 个股资金历史 |
big_deal_flow | stock_fund_flow_big_deal | 大单追踪末级兜底 |
Notes
- Final primary/secondary order is not auto-approved; every downgrade chain is confirmed with user review.
- Validation evidence is recorded in
docs/sentiment/reports/akshare_interface_validation_latest.md.
AKShare Interface Validation Report (Manual + Scripted)
This document is generated/maintained from:
scripts/sentiment/run_akshare_interface_validation.pydocs/sentiment/reports/akshare_interface_validation_latest.md
Scope
- Focus on first-wave 6 interfaces used by four sentiment tools.
- Validation dimensions:
- availability (
ok) - latency (
elapsed_ms) - shape stability (
columns_sample) - minimum records (
record_count)
Latest run
Run command:
python3 scripts/sentiment/run_akshare_interface_validation.pyArtifacts:
docs/sentiment/reports/akshare_interface_validation_latest.jsondocs/sentiment/reports/akshare_interface_validation_latest.md
Optional dependency note
akshare-proxy-patchis supported as an optional enhancement, not a required dependency.- Install only when needed:
python -m pip install -r requirements-optional.txt- In this project, the primary stability baseline remains:
- bypass proxy environment for Eastmoney-sensitive AKShare calls (
without_proxy_env) - fallback chain + quality gate + cache
Classification policy
production_ready: success and quality gate passed.fallback_only: callable but unstable in record count/latency.temporarily_unavailable: repeated errors or malformed payload.
Decision gate
- This report provides evidence only.
- Final primary/secondary call order is reviewed with user before marked approved.
Sentiment Tools API Contract
Applies to:
tool_fetch_limit_up_stockstool_fetch_a_share_fund_flowtool_fetch_northbound_flowtool_fetch_sector_data
Unified top-level fields
success: boolsource: winner data sourcefallback_route: attempted sources in orderused_fallback: whether winner is not first sourceattempts: source-level attempt recordsas_of: generation timestampdata_quality:fresh | cached | partialcache_hit: boolerror_code: nullable, e.g.UPSTREAM_FETCH_FAILEDerror_message: nullableexplanation: short human-readable explanationquality_score: int in \[0, 100\] — heuristic composite (freshness, fallback, completeness); seeplugins/utils/response_quality.pydata_generated_at: optional string — when present, must equalas_of(alias for consumers that expect an*_atsuffix)
Global fields injected by tool_runner.py
These apply to all tools invoked via tool_runner.py (not only sentiment):
elapsed_ms: int — wall-clock duration of the invocation in the runner processtool: string — tool id (e.g.tool_fetch_limit_up_stocks)plugin_version: string — mirrorsversioninopenclaw.plugin.json
See also ../optimization/tool_response_metadata.md.
Backward compatibility
Existing business fields are preserved (e.g. data, records, leaders, signal).
Example (abbreviated)
{
"success": true,
"source": "akshare.stock_zt_pool_em",
"fallback_route": ["akshare.stock_zt_pool_em"],
"used_fallback": false,
"attempts": [{"source":"akshare.stock_zt_pool_em","ok":true,"message":"20260418"}],
"as_of": "2026-04-18 11:00:00",
"data_quality": "fresh",
"cache_hit": false,
"error_code": null,
"error_message": null,
"explanation": "...",
"quality_score": 88,
"data_generated_at": "2026-04-18 11:00:00",
"elapsed_ms": 120,
"tool": "tool_fetch_limit_up_stocks",
"plugin_version": "0.5.3"
}---
Skill aggregate: market-sentinel
Applies to the structured narrative output produced when the agent follows skills/market-sentinel/SKILL.md (not a single tool_runner tool). Numeric bands and weights are defined in skills/market-sentinel/config/market-sentinel_config.yaml (sentiment_stage_thresholds, risk_modes, dynamic_weight_adjustment).
Top-level fields (full report)
| Field | Type | Required | Description |
|---|---|---|---|
overall_score | number | yes | Composite 0–100 after re-normalization when tools are missing. |
sentiment_stage | string | yes | One of: 冰点, 修复, 震荡, 混沌, 高潮, 退潮. |
sub_scores | object | yes | Four keys, each 0–100: limit_up_ecology, fund_flow_attitude, northbound_trend, sector_structure. |
factor_attribution | object | yes | At least leading, lagging (sub-score dimension keys) and notes (string). |
data_completeness_ratio | number | yes | In \[0,1\], e.g. successful tools / 4. |
action_bias | string | yes | One of: 进攻, 均衡, 防守. |
risk_counterevidence | array | yes | List of strings (or objects with text), non-empty when any tool failed or signals conflict. |
confidence_band | string | yes | low \ |
degraded | boolean | yes | true if any dependency tool failed or was skipped after partial success. |
overall_score → sentiment_stage (v1.0 default bands)
Bands below are normative for contract tests; deploy may override via config only.
overall_score (inclusive range) | sentiment_stage |
|---|---|
| 0–20 | 冰点 |
| 21–35 | 修复 |
| 36–50 | 震荡 |
| 51–65 | 混沌 |
| 66–85 | 高潮 |
| 86–100 | 退潮 |
`混沌` override: if max(sub_scores) − min(sub_scores) ≥ chaos_subscore_spread_min from config, sentiment_stage SHOULD be 混沌 even when overall_score maps elsewhere; record the override in factor_attribution.notes.
Degraded report (fixed template)
When degraded is true, the same top-level keys MUST still be present. Use these conventions:
risk_counterevidence: MUST include one entry per failed tool, e.g.northbound: upstream unavailable.data_completeness_ratio: MUST reflect successful tools only.confidence_band: SHOULD belowormediumunless remaining evidence is exceptionally strong.overall_score: MUST be recomputed from available sub-scores only (re-normalized weights per config).
Insufficient evidence shape
When the skill cannot justify a composite view:
| Field | Type | Required |
|---|---|---|
status | string | yes, literal insufficient_evidence |
reason | string | yes |
data_completeness_ratio | number | yes |
missing_tools | array of strings | yes (tool ids or short names) |
No requirement to populate overall_score / sentiment_stage in this shape.
Minimal JSON example (full report, abbreviated)
{
"overall_score": 45,
"sentiment_stage": "震荡",
"sub_scores": {
"limit_up_ecology": 62,
"fund_flow_attitude": 55,
"northbound_trend": 60,
"sector_structure": 52
},
"factor_attribution": {
"leading": "limit_up_ecology",
"lagging": "sector_structure",
"notes": "涨停分项略高于其他三项。"
},
"data_completeness_ratio": 1.0,
"action_bias": "均衡",
"risk_counterevidence": ["北向与内资单日方向不一致,降低进攻置信度。"],
"confidence_band": "medium",
"degraded": false
}Sentiment Data Quality Policy
Quality gate checks
- Structure: required fields present.
- Scale: minimum record threshold by object type.
- Null ratio: reject if null ratio exceeds configured threshold.
Thresholds (initial)
limit_up_pool: min 5 records on single-day querysector_snapshot_industry: min 30 recordssector_snapshot_concept: min 10 recordsfund_flow_rank: min 1 record, null ratio <= 0.85
Quality labels
fresh: upstream passed gatecached: returned from local TTL cachepartial: returned with reduced confidence or failed gate fallback
Sentiment Error Codes
| error_code | meaning | action |
|---|---|---|
VALIDATION_ERROR | invalid request argument | fix request parameters |
UPSTREAM_FETCH_FAILED | all sources failed or quality gate rejected | retry later / inspect attempts |
UPSTREAM_TIMEOUT | upstream timeout exceeded | use lower scope or rely on cache |
RUNTIME_ERROR | unexpected internal error | inspect traceback and open issue |
{
"generated_at": "2026-04-18 16:43:39",
"api_signatures": {
"stock_zt_pool_em": "(date: str = '20241008') -> pandas.DataFrame",
"stock_market_fund_flow": "() -> pandas.DataFrame",
"stock_sector_fund_flow_rank": "(indicator: str = '今日', sector_type: str = '行业资金流') -> pandas.DataFrame",
"stock_individual_fund_flow_rank": "(indicator: str = '5日') -> pandas.DataFrame",
"stock_hsgt_fund_flow_summary_em": "() -> pandas.DataFrame",
"stock_sector_spot": "(indicator: str = '新浪行业') -> pandas.DataFrame",
"stock_board_industry_name_em": "() -> pandas.DataFrame"
},
"cases": [
{
"name": "stock_zt_pool_em",
"ok": false,
"elapsed_ms": 10096,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
},
{
"name": "stock_market_fund_flow",
"ok": false,
"elapsed_ms": 10116,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
},
{
"name": "stock_sector_fund_flow_rank",
"ok": false,
"elapsed_ms": 10140,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
},
{
"name": "stock_individual_fund_flow_rank",
"ok": false,
"elapsed_ms": 10098,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
},
{
"name": "stock_hsgt_fund_flow_summary_em",
"ok": false,
"elapsed_ms": 10053,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
},
{
"name": "stock_sector_spot_行业",
"ok": false,
"elapsed_ms": 10009,
"record_count": 0,
"columns_sample": [],
"error": "Expecting value: line 1 column 1 (char 0)"
},
{
"name": "stock_board_industry_name_em",
"ok": false,
"elapsed_ms": 35017,
"record_count": 0,
"columns_sample": [],
"error": "('Connection aborted.', ConnectionResetError(104, 'Connection reset by peer'))"
}
]
}多 Skill 编排(Step B 参考)
目标
在 Agent 会话中 顺序或并行 调用多个本仓库 Skill 时,统一合并输出与冲突处理。
推荐模式(类 TEAM_RESULT)
1. 分工:每个 Skill 只承担其 SKILL.md 边界(如 technical-analyst 不负责资金流)。 2. 事实层:先拉齐 L3/L4-data 工具 JSON,再进入各 Skill 叙述。 3. 合并字段:建议外层结构 { "skills": [...], "evidence_index": [...], "conflicts": [] }。 4. 冲突:同一指标不同工具结论时,写入 conflicts 并降低 confidence_band,不得强行二选一叙事。
禁止
- 绕过
tool_runner/ manifest 直接 import 采集实现。 - 在合并层输出买卖/仓位建议(划归助手 L4-decision)。
"""
ETF数据采集插件
"""
Related skills
How it compares
Use as the OpenClaw data plugin layer, not as a full fundamental or backtest methodology skill on its own.
FAQ
Who is openclaw-data-china-stock for?
Developers using OpenClaw to automate China A-share, ETF, and option data collection inside agent workflows.
When should I use openclaw-data-china-stock?
During Validate when scoping instruments and data needs, during Idea when researching market structure, and during Grow when refreshing analytics pipelines—any time your agent must fetch or read cached China market series.
Is openclaw-data-china-stock safe to install?
Review the Security Audits panel on this Prism page and inspect packaging excludes; the skill touches network APIs and may write local Parquet or DB caches on disk.