Openclaw Data China Stock
A-share / ETF / option data for OpenClaw: unified market_data, P0/P1 tools, onshore fund flow (tool_fetch_a_share_fund_flow), technical screeners (tool_fetch_a_share_technical_screener), stock views, multi-source fallback.
Install
openclaw plugins install clawhub:@shaoxing-xie/openclaw-data-china-stockopenclaw-data-china-stock
为 OpenClaw 打造的中国市场数据底座：覆盖 A 股、ETF、指数、期权、资金流、技术指标与宏观分析。
一句话概述：为 OpenClaw Agent 提供统一行情采集、58 指标计算，并以“工具+Skill”成对输出投研能力。
v0.5.0 升级亮点（单版本）
- 新增 5 个 Skill，与现有宏观 Skill 组成 6 大分析方向：
technical-analystmarket-scannerfund-flow-analyststrategy-backtester（MVP 轻回测编排）fundamental-analystchina-macro-analyst（既有）
- 能力结构从“工具可调用”升级为“工具 + Skill 可直接消费”：
- 工具层负责数据采集与计算
- Skill 层负责结构化分析、证据约束、风险反证与统一输出契约
- 发布策略：本次 5 个 Skill 一次性升级发布（非分步小版本）
为什么你会需要它
在 A 股量化/投研工作流里，常见痛点通常是：
- 单一数据源不稳定，接口变动后维护成本高
- 指标实现繁琐，跨环境依赖不一致（TA-Lib/pandas-ta）
- 指标口径与本地行情软件不一致，难以校验
- 宏观数据收集分散，难以快速形成结构化结论
- 采集、分析、Agent 调用链路割裂，难以自动化
这个项目的目标是将上述问题收敛为一个可复用、可扩展、可直接被 Agent 调用的插件层。
数据分层速览（L1 / L2 / L3 / L4-data）
下表便于与宿主「统一数据层」文档对照；细则与契约以 docs/data_model/、docs/schemas/ 为准（README 不重复长文）。
| 层级 | 在本插件中的含义 | 典型工具 / 模块 |
|---|---|---|
| L1 | 原始采集、Provider 编排、append-only 风格落盘 | tool_fetch_market_data、tool_fetch_index_data（含 global_spot）、tool_read_market_data 等 |
| L2 | 实体解析、静态/主数据卡片 | tool_resolve_symbol、tool_get_entity_meta（plugins/data_collection/entity/） |
| L3 | 特征、聚合、门闸类产出（研究/决策向） | 多因子选股、情绪四工具、轮动 tool_etf_rotation_research 等 |
| L4-data | 确定性估值快照（非投资建议，结构化字段 + _meta） | tool_l4_valuation_context、tool_l4_pe_ttm_percentile；Schema：docs/schemas/valuation_context_v1.schema.json、docs/schemas/pe_ttm_percentile_band_v1.schema.json |
因子与 catalog 运行时对齐：config/factor_registry.yaml + plugins/utils/plugin_data_registry.py（说明见 docs/data_model/catalog_runtime_alignment.md）。
数据源健康与可观测
- 探针工具：
tool_probe_source_health（write_snapshot=true时写入data/meta/source_health_snapshot.json，并维护data/meta/source_health_history_rollup.json等趋势文件）。 - 只读 digest：
tool_plugin_catalog_digest；attempts 聚合：tool_summarize_attempts。 - 全球指数 spot：
tool_fetch_global_index_spot等返回中可含source_route（含catalog_merge、active_priority）、attempts、elapsed_ms等排障字段。
宿主 etf-options-ai-assistant 的 Chart Console 通过 HTTP 只读消费上述快照（见对方 README.md 与 docs/data-source-contract.md）。
核心能力
1) 全资产行情采集
- 统一入口：
tool_fetch_market_data（index/etf/stock/option） - 缓存读取：
tool_read_market_data - A 股专题：资金流、技术选股、盘前分时、估值快照、板块轮动等
- 多源回退与容错：降低单源故障对工作流的影响
2) 技术指标引擎（58 指标）
- 工具：
tool_calculate_technical_indicators - P0/P1/P2 全量共 58 指标（趋势、动量、波动、形态、统计）
- 引擎优先级：
TA-Lib -> pandas-ta -> builtin - 输出模式：
append/standalone - 结构化错误码：
VALIDATION_ERROR/UPSTREAM_EMPTY_DATA/UPSTREAM_FETCH_FAILED/RUNTIME_ERROR
详见：plugins/data_collection/technical_indicators/README.md
3) 宏观数据与分析（v0.4.0+）
- 统一宏观入口：
tool_fetch_macro_data(dataset, latest_only, lookback, frequency)tool_fetch_macro_snapshot(scope, include_quadrant)
- 兼容入口：
tool_fetch_macro_*（兼容旧工作流） - 宏观 Skill：
skills/china-macro-analyst/SKILL.md - 对外契约与数据质量文档：
docs/macro/api_contract.mddocs/macro/error_codes.mddocs/macro/dq_policy.md
4) 多因子选股（A 股）
- 工具：
tool_screen_equity_factors；等价别名tool_screen_by_factors（同一实现与参数信封，便于宿主工作流统一 manifest id） - 实现：
plugins/analysis/equity_factor_screening.py；manifest /tool_runner已注册 - 批量：
tool_batch_fetch白名单含上述工具（plugins/merged/tool_batch_fetch.py） - 申万一级静态映射：
config/sw_industry_level1_mapping.json←scripts/update_sw_industry_level1_mapping.py - 契约与测试：
docs/schemas/tool_screen_equity_factors.schema.json、tests/test_tool_screen_equity_factors_contract.py - 与 etf-options-ai-assistant 协同：夜盘收尾
tool_finalize_screening_nightly、规程 Skillota_equity_factor_screening_brief在该仓配置（见该仓config/tools_manifest.yaml、skills/ota-equity-factor-screening-brief/）；集成总览见该仓docs/integration/plugin_assistant_integration_plan.md
5) Skill 能力层（v0.5.0+）
- 技术分析：
skills/technical-analyst/SKILL.md - 市场扫描：
skills/market-scanner/SKILL.md - 市场情绪综合：
skills/market-sentinel/SKILL.md（四情绪工具聚合；聚合 JSON 契约见docs/sentiment/api_contract.md中 Skill aggregate 一节） - 资金流分析：
skills/fund-flow-analyst/SKILL.md - 策略回测（MVP）：
skills/strategy-backtester/SKILL.md - 基本面分析：
skills/fundamental-analyst/SKILL.md - 宏观分析（既有）：
skills/china-macro-analyst/SKILL.md - 统一规范：
skills/SKILL_CONTRACT.md
6) 四个情绪工具（已完成优化收口）
- 覆盖工具：
tool_fetch_limit_up_stockstool_fetch_a_share_fund_flowtool_fetch_northbound_flowtool_fetch_sector_data
- 统一能力：
- 多源降级链 + 质量闸门（结构/规模/null_ratio）
- 统一响应契约（
success/source/fallback_route/attempts/data_quality/explanation） - 交易时段差异化 TTL 缓存（盘中/盘后/日终）
- 衍生指标本地计算（不污染上游原始数据）
- 明确原则：
- 无上游且无缓存时直接失败，不生成估计值
- 缓存仅来自历史成功拉取结果，不做虚构填补
- 关键链路（已拍板）：
limit_up_pool:akshare.stock_zt_pool_em -> stock_zt_pool_previous_em -> stock_zt_pool_strong_em -> stock_zt_pool_sub_new_em -> cachefund_flow:THS-first（东财兜底可选且默认关闭）northbound:tushare.moneyflow_hsgt -> eastmoney.legacy_hsgt -> cachesector_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
- industry:
- 详细文档：
docs/sentiment/api_contract.mddocs/sentiment/dq_policy.mddocs/sentiment/error_codes.mddocs/sentiment/akshare_interface_inventory.mddocs/sentiment/akshare_interface_validation_report.mddocs/sentiment/sentiment_data_object_call_chains.mddocs/sentiment/examples.md
7) 面向 OpenClaw Agent 的工程化集成
config/tools_manifest.json+tool_runner.py统一路由- 支持开发态快速注册：
scripts/register_openclaw_dev.py - 解释器解析优先级明确，便于跨环境部署
8) 与交易助手（etf-options-ai-assistant）协同
宿主仓库通过 plugins/data_collection 符号链接 或环境变量 OPENCLAW_CHINA_STOCK_PLUGIN_ROOT / OPENCLAW_DATA_CHINA_STOCK_REPO 指向本仓库，复用本插件的采集与部分分析工具；宿主侧用 plugins/china_stock_upstream.py 对 equity_factor_screening、l4_data_tools 等模块做 临时 sys.path 注入（勿在宿主 plugins/utils/ 下新增会遮蔽本插件 plugins.utils 的薄封装）。
已对宿主暴露或与之对齐的能力要点：
| 能力 | 说明 |
|---|---|
| 全球指数 spot | tool_fetch_global_index_spot / fetch_global_index_spot 响应含 source_route（含 catalog_merge、active_priority）；宿主在运维环境变量 OPTION_TRADING_ASSISTANT_DEBUG_PLUGIN_CATALOG=1 下可将上述字段透出到 Chart / 报告诊断 |
| L4 估值 | tool_l4_valuation_context、tool_l4_pe_ttm_percentile；宿主 Chart Console 提供只读 HTTP 视图并落盘 data/semantic/l4_* |
| 观测 | tool_plugin_catalog_digest、tool_summarize_attempts |
| 选股 | tool_screen_by_factors 与 tool_screen_equity_factors 等价 |
真源文档（宿主仓）：etf-options-ai-assistant/docs/integration/plugin_assistant_integration_plan.md。
快速开始
优先参考：INSTALL.md（源码安装 / 打包安装 / 环境变量 / 验收命令）。
安装方式（ClawHub）
openclaw plugins install clawhub:@shaoxing-xie/openclaw-data-china-stock
如你的 OpenClaw CLI 版本不支持 clawhub: 前缀，可改用：
openclaw plugins install @shaoxing-xie/openclaw-data-china-stock
安装方式（源码开发）
cd /path/to/openclaw-data-china-stock
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt
如你的网络环境对 AKShare 东方财富链路有额外限制，可按需安装可选增强依赖（非必需）：
python -m pip install -r requirements-optional.txt
开发环境一键注册（推荐）
.venv/bin/python scripts/register_openclaw_dev.py
该脚本会以“仅追加、不破坏原配置”的方式更新 ~/.openclaw/openclaw.json，并将相关 skill 暴露到 OpenClaw workspace。
情绪工具相关环境变量（可选）
四个情绪工具中，tool_fetch_northbound_flow 优先使用 tushare.moneyflow_hsgt。
如需启用该主链路，请配置：
export TUSHARE_TOKEN="your_tushare_token"
说明：
- 未配置
TUSHARE_TOKEN时，工具会自动降级到eastmoney.legacy_hsgt -> cache moneyflow_hsgt为日频汇总口径，适合日终趋势分析（非盘中实时明细）- 建议在服务进程环境或
~/.openclaw/.env中统一注入该变量
常见使用示例（Agent 指令）
- “请拉取 510300 最近一年日线并计算 RSI、MACD、布林带。”
- “请给出今日 A 股资金流最强行业和对应 ETF。”
- “请输出最新宏观快照，并判断当前美林时钟象限。”
- “请做一份 510300 技术面分析，输出趋势/动量/波动和风险反证。”
- “请扫描当前盘中市场，给出情绪阶段与异动清单。”
- “请解读今天主力与北向资金是否共振。”
- “请给出贵州茅台基本面四维评分和估值偏离。”
- “请对 510300 的均线策略做回测评估，并说明当前是 MVP 模式限制。”
命令行快速验证（tool_runner.py）
在仓库根目录、已激活 .venv 的前提下，可直接跑工具 JSON（与 OpenClaw / CI 一致）：
# 实体解析（L2）
.venv/bin/python tool_runner.py tool_resolve_symbol '{"symbol":"sh600519"}'
# L4 估值上下文（示例标的；需上游数据可用）
.venv/bin/python tool_runner.py tool_l4_valuation_context '{"stock_code":"600519","trade_date":""}'
# 数据源健康探针（写快照需显式打开写盘参数，详见工具 manifest）
.venv/bin/python tool_runner.py tool_probe_source_health '{"write_snapshot":true}'
Agent 会话内则通过 OpenClaw 注册的同名 tool_* 调用即可。
文档导航
- 安装与部署：
INSTALL.md - 技术指标明细：
plugins/data_collection/technical_indicators/README.md - Skill 总规范：
skills/SKILL_CONTRACT.md - 技术分析 Skill：
skills/technical-analyst/SKILL.md - 市场扫描 Skill：
skills/market-scanner/SKILL.md - 市场情绪综合 Skill：
skills/market-sentinel/SKILL.md - 资金流分析 Skill：
skills/fund-flow-analyst/SKILL.md - 策略回测 Skill：
skills/strategy-backtester/SKILL.md - 基本面分析 Skill：
skills/fundamental-analyst/SKILL.md - 宏观 Skill：
skills/china-macro-analyst/SKILL.md - 宏观 API / 错误码 / 数据质量：
docs/macro/api_contract.mddocs/macro/error_codes.mddocs/macro/dq_policy.md
- 数据模型与实体 / meta 契约：
docs/data_model/（entity_id.md、meta_contract.md、catalog_runtime_alignment.md） - 跨仓契约对齐清单（宿主 ↔ 插件）：
docs/cross_repo/assistant_schema_sync_checklist.md - JSON Schema（L4 等）：
docs/schemas/ - 多 Skill 编排说明：
docs/skills/multi_skill_orchestration.md - 并发与上游运维注意：
docs/operations/max_concurrent_upstream.md - 版本发布记录：
CHANGELOG.md v0.5.2发布纪要：docs/release/v0.5.2.md- 与 etf-options-ai-assistant 的集成与契约演进：见对方仓库
docs/integration/plugin_assistant_integration_plan.md
兼容性与已知限制
- 兼容旧流程：
tool_fetch_macro_*兼容入口仍保留。 strategy-backtester当前为 MVP 编排模式：- 基于
tool_fetch_market_data+tool_calculate_technical_indicators - 未引入独立
tool_backtest_*专用工具链 - 输出会显式声明能力边界与限制
- 基于
回归测试
完整测试：
python -m pytest -q tests/
最小关键链路测试：
python -m pytest -q tests/test_manifest_tool_map_parity.py tests/test_tool_runner_dispatch.py tests/test_technical_indicators_tool.py
运行说明
缓存策略
默认 data_cache.enabled=false：
- 允许读取已有缓存文件
- 默认不写入新的 parquet 缓存
仅在需要本地读写缓存时，将 config.yaml 中 data_cache.enabled 设为 true。
返回字段约定
大多数工具返回：
successdatamessagesource
部分工具会补充 count、timestamp、cache_hit、provider、fallback_route、attempt_counts 等字段，用于排障和可观测性。
四个情绪工具额外统一遵循：
data_quality:fresh | cached | partialattempts: 每个上游源调用结果used_fallback: 最终命中是否为降级路径error_code/error_message: 上游失败可诊断信息explanation: 可读解释（供第三方直接消费）
贡献
欢迎提交 Issue / PR：
- 发现问题或提需求：GitHub Issues
- 提交改进：基于
main发起 PR
许可证
MIT
免责声明
本项目用于数据采集与技术研究，不构成投资建议。
致谢
宏观与行情生态能力基于开源社区（如 AKShare）提供的数据接口与工程实践。