朝阳永续-金融文档检索

概述

suntime-financial-docs

独立取数 skill：调用 suntime-financial-docs MCP，共 12 个工具（5 对列表+检索 + 2 个独立检索），覆盖公告/研报/新闻/财报原文的元数据列表与 RAG 语义检索。

依赖： suntime-mcp-cli CLI（安装、鉴权、--params 写法见 references/mcp-cli.md）。

前置条件

首次使用按 references/mcp-cli.md「快速开始」完成环境准备（安装 CLI → 配置 Key → 注册本 MCP → 验证，约 2 分钟）；已就绪可跳过。

运行时错误处理（调用失败时自动引导）

以下两类错误改参数无法解决，需自动为用户打开浏览器引导处理（无图形界面的云端环境改为直接把链接给用户）。按调用输出中的关键词匹配，不依赖退出码：

打开浏览器命令：macOS open <url>；Windows start <url>；Linux xdg-open <url>。

其余技术性错误（JSON 引号、session 过期、工具名拼错、类型拦截等）AI 可按 CLI 提示自行修正，完整对照见 references/mcp-cli.md「故障排查」。

标准调用流程（必须遵守）

每次构造工具调用前，都必须经过以下三步，不得跳过第 1-2 步。

# ── 第 1 步：确认工具名（从工具速查表选定候选后，用 tool_list 核验拼写；加 --refresh 可强制刷新缓存）
suntime-mcp-cli suntime-financial-docs tool_list 2>&1 | grep "^- "

# ── 第 2 步：查参数 schema（每次调用前必做，本地缓存零网络开销）──────
suntime-mcp-cli suntime-financial-docs tool_list 2>&1 | grep -A 40 "^- <tool_name>$"
# 重点确认：① required 里有哪些参数（本 MCP 检索类工具必填是 query；
#           列表类仅 get_etf_announcement_list 必填 sec_ids，
#           get_stock_announcements_list / get_hkstock_announcements_list 全部参数可选，其余列表工具以实时 schema 为准）
#           ② 可选参数有哪些（start_time / end_time / sec_ids / tags / data_scope / limit / ann_id / report_id / financial_report_tags）

# ── 第 3 步：调用────────────────────────────────────────────────
suntime-mcp-cli suntime-financial-docs <tool_name> --params '<JSON>'

⚠️ 参数名必须来自第 2 步查到的 schema，禁止凭记忆或类比其他工具构造。 本 MCP 所有检索类工具的语义检索参数统一叫 query（没有 keyword / keywords / q）。

本 skill 文档静态维护，以 tool_list 实时输出的 schema 为最终权威；tool_list 本地缓存 1 小时，缓存命中时纯本地执行，零网络开销。CLI 在发出请求前还会自动校验（工具名 + 必填参数 + 类型），校验不通过时按 CLI 提示修正（单复数误用/类型可转换场景可加 --fix 自动修正，详见 references/mcp-cli.md「调用前校验」节），但那是报错兜底，不能替代先查 schema 再构造参数。

本 MCP 是文本检索（RAG），返回的是公告/研报/新闻的原文段落，适合"找原文 / 找观点 / 找事件解读"。如需结构化数字（如营收、净利润、PE），优先用 suntime-find-fin-data（suntime-stock）的对应工具。

工具速查表（共 12 个）

⚠️ 下表的「必填参数」列为静态维护、可能滞后；每个工具的准确参数名与类型以 tool_list 实时 schema 为准（查询方式见上方「标准调用流程」第 2 步）。

📅 日期参数分两组：资讯 / A 股 / 港股的 6 个工具（news、stock×3、hkstock×2）用 start_time + end_time（yyyy-MM-dd HH:mm:ss，可精确到时分秒，纯日期也兼容）；研报 / ETF 的 6 个工具用 start_date + end_date（yyyy-MM-dd）。均可选，不传 = 不限时间。用户未指定时间时建议套默认窗口、空结果再扩大重试（见下文「默认时间窗口」）。

📋 列表 vs 检索：公告/研报/ETF 公告提供成对的 get_xxx_list（元数据列表，快速浏览目录/事件清单）和 search_xxx（RAG 语义检索，深挖原文内容）。先 list 拿目录/事件清单及 ID，再 search 传 ID 精准召回原文。财报没有独立列表工具，元数据清单用 get_stock_announcements_list + tags=402101,402102 替代（见「全市场事件盘点」模式）。

📰 新闻 / 财报 / 公告

📊 研报

📋 ETF 公告

关键参数 Schema

query（7 个检索类工具必填；2 个列表工具无需）

• 自然语言问句，必须具体、明确
• ❌ 反例："贵州茅台经营情况"（太宽泛）
• ✅ 正例："贵州茅台 2025 年年报中提到的 2026 年增长目标与策略"

⚠️ 降级重试时 query 必须改写：若上一轮无结果触发了第 2 轮重试，严禁传入与上一轮完全相同的 query，要用同义表达、扩大语义颗粒度。

💡 部分工具的 query 支持嵌入多种筛选要素：在 query 中自然表述机构、分类、评级、标签等可大幅提升检索精度，详见 references/query_enhance.md。

时间范围参数（两组参数名）

• 两个参数均为可选：不传 = 不限时间；只传一端 = 单边限制。用户未表达任何时间意图时，按下方「默认时间窗口」兜底，避免裸查全库
• 日期参数的填写逻辑遵循「报告期 ≠ 发布期」规则（见下方表格）

核心规则：报告期 ≠ 发布期。

默认时间窗口（用户未指定时间时套用）

不同内容生命周期不同，按工具分档给默认值——避免旧内容淹没召回、同时控制积分消耗。相对窗口一律按对话当前日期换算为绝对 yyyy-MM-dd：

应用原则：

• 仅当用户未表达任何时间意图时套默认；用户说了"2025 年年报""去年""近一周"等 → 按用户意图换算（财报还要做报告期 ≠ 发布期换算），不走默认
• 套用后在回复里点明所用窗口（如"默认检索近 30 天新闻"），方便用户一句话扩展 / 收窄

空结果 → 扩大窗口重试

按默认窗口检索无结果时，不要直接回复"未找到"，按下表扩大时间窗重试一次：

• 重试仍属降级重试，query 按注意事项第 4 条改写（同义扩展、放大语义颗粒度），不要原样复用上一轮 query
• 每次重试后在回复里说明实际所用窗口

sec_ids

所有工具的证券代码参数统一用 sec_ids，格式带 .SH/.SZ/.HK/.SW 后缀。多个用英文逗号分隔，最多 10 个。

⚠️ 多代码的返回完整性因工具而异：get_xxx_list 列表工具多代码合并查询完整；search_xxx RAG 检索工具传多个代码时召回可能只覆盖部分标的（且总条数被压缩），不会报错提示缺失。因此：

• 列表/盘点类：放心多代码合并，一次拿全
• RAG 深挖类：需要每家都召回原文时，按代码拆分多次单查（每查 1 个代码）；仅做开放式探索、不要求穷尽时才可多代码合传

⚠️ ETF 研报 search_etf_research_reports 的 sec_ids 必须带后缀（510300.SH），不要传 6 位纯数字代码。

get_stock_announcements_list / get_hkstock_announcements_list：单股与全市场两种模式

A 股与港股列表工具同构，sec_ids 均为可选（港股无需 query）：

返回字段：id（= 检索工具的 ann_id）、name（公告标题）、publish_time（发布时间）、sec_id、sec_name（研报/ETF 列表为 date_about）。港股返回为多区块结构（见 tags 章节说明）。列表返回按发布时间降序排列——返回条数等于 limit 时说明可能截断，缩小时间范围分段多次获取。

⚠️ tag 粒度提醒：402101（财报）涵盖年报/半年报/季报的正式报告，402102（业绩预告）会混入业绩快报、业绩预告更正、主要经营情况公告等，tag 只是初筛，拿到列表后按公告标题（name）分桶（含"业绩预告"→ 预告、含"业绩快报"→ 快报、含"半年度报告"→ 正式财报）。盘点类任务标题本身就是明文分类依据。

data_scope（search_stock_announcements / get_stock_announcements_list，可选）

默认 "4,14,17,20" 全开（不传 = 全部数据源）。多个用英文逗号分隔。

tags（公告标签：get_stock_announcements_list / search_stock_announcements / get_hkstock_announcements_list / search_hkstock_announcements）

A 股 / 港股同码，A 股仅在 data_scope=4 时生效，港股直接使用，多个逗号分隔。高频标签速记：

完整 26 个标签枚举见 references/tags.md。

港股 get_hkstock_announcements_list / search_hkstock_announcements 使用同一套标签码。两个港股工具的返回都是按类型分组的多块结构（如「公告」「业绩说明会」区块并列挂在返回 JSON 顶层、不在 data 键下，与 A 股工具的 data.rows 不同），解析时需遍历各区块；tags 对「公告」区块生效。

financial_report_tags（仅 search_stock_financial_reports，A 股财报投研标签）

按投研主题过滤财报原文段落，多个逗号分隔。优先带此参数检索（更精准），空结果或条数过少时再剔除重试。24 个标签（6 大类：外部环境 501xxx / 公司业务 502xxx / 经营表现 503xxx / 战略与展望 504xxx / 风险 505xxx / 资本与治理 506xxx）完整枚举与示例见 references/tags.md。

ann_id / report_id（检索工具通用，精准召回）

所有 search_xxx 检索工具均支持传入 ID 实现精准检索，ID 从对应的 get_xxx_list 列表工具获取：

两种使用场景（所有检索工具通用，A 股/港股公告、研报、ETF 公告均适用）：

• 场景 A：先调 get_xxx_list 拿到 ID（可多个，英文逗号分隔），再传给 search_xxx 精准召回原文
• 场景 B：忽略 ID，直接用 query + sec_ids + 时间范围跨全库语义检索

示例见「单股检索」路径 B（A 股公告/研报）与 references/patterns.md（ETF 公告，同一范式）。

limit（列表工具通用，可选）

所有 get_xxx_list 工具均支持 limit 参数控制返回条数，最大 200，默认 20。

query 参数增强（部分工具）

以下工具的 query 参数支持在自然语言中嵌入筛选要素（机构、分类、评级、标签等）以实现高质量精准检索，详见 references/query_enhance.md：

常见查询模式

工具路由：按"要清单还是要原文"选工具

判断口诀：要"清单/目录/枚举" → list 工具；要"原文/观点/解读" → search 工具。区分第 3、4 行的关键是问题里有没有"清单型限定词"（本周/上周/某段时间/汇总/盘点/明细 → 场景 3，穷尽枚举必须走 list）；纯主题问句没有时间穷尽要求 → 场景 4，裸 query 即可。

⚠️ 场景 3 直接调 search_xxx 裸 query 是最常见误用：RAG 检索面向"内容语义"，宽泛的时间枚举型 query（如"本周业绩快报"）召回既可能为空、也无法保证穷尽。反之场景 4 不必绕道 list——开放式主题本来就没有可枚举的清单。

全市场事件盘点（list 扫描 → 按标题分桶 → ann_id 批量深挖）⭐ 盘点型任务标准链路

典型问题："提取本周业绩预告、业绩快报和半年报，汇总生成日报"——无具体标的、要按时间窗穷尽枚举。

第 1 步：get_stock_announcements_list 全市场扫描（不传 sec_ids，用 tags + 日期窗圈定范围）

# 业绩预告/快报：tag 402102 混含预告、快报、更正、经营情况公告
suntime-mcp-cli suntime-financial-docs get_stock_announcements_list --params '{"data_scope":"4","tags":"402102","start_time":"2026-08-17 00:00:00","end_time":"2026-08-20 23:59:59","limit":200}'

# 正式财报（半年报）：tag 402101；标题含"半年度报告"即目标，"摘要"版可只作参考
suntime-mcp-cli suntime-financial-docs get_stock_announcements_list --params '{"data_scope":"4","tags":"402101","start_time":"2026-08-17 00:00:00","end_time":"2026-08-20 23:59:59","limit":200}'

一次扫描可同时传 "tags":"402101,402102" 再分桶，减少一次调用。列表按 publish_time 降序返回：返回条数 = limit 即可能截断，把时间范围对半缩小分段多扫，直至返回条数 < limit。财报披露高峰期（年报季 4 月、中报季 8-9 月）一周正式财报可达数百条，limit 用满 200 仍截断时按日甚至按时段拆分。

第 2 步：按公告标题（name）分桶

对返回 rows 逐条看 name：含「业绩预告」→ 预告桶；含「业绩快报」→ 快报桶；含「半年度报告」→ 财报桶；其余（更正公告、经营情况公告等）按需归置。分桶即日报的"明细"骨架（sec_name / name / publish_time / id）。正式财报条数多时，明细可只列"摘要"版，全文数字按需抽查。

第 3 步：ann_id 批量精准召回原文（补齐明细数字 + 支撑点评）

# 逗号拼接多个 id（可批量）；query 描述要提取的内容维度
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"2026年半年度业绩预告或业绩快报 预计净利润 同比变动","data_scope":"4","ann_id":"10441076,10429025,10428574"}'

条数多时分批（如每批 10 个 id）多次召回；每批 query 聚焦该批公告共同的提取维度。投资经理点评：以第 3 步召回的原文数字为据（预增/预减幅度、盈亏原因表述），不要凭标题臆测。

补充：search_stock_announcements 也支持 tags 过滤（402101,402102 可用），在无 ann_id 的轻量场景可与日期窗组合使用；但穷尽枚举仍以列表工具为准，search 的召回条数不可控。

单股检索：公告 / 研报 / 财报原文

路径 A（默认）：直接语义检索——query + sec_ids 一步到位，适合"看某方面的内容"：

# 公告（start_time/end_time 可选）
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"贵州茅台 2025 年度业绩预告","start_time":"2026-01-01","end_time":"2026-04-30","data_scope":"4","sec_ids":"600519.SH"}'

# 研报
suntime-mcp-cli suntime-financial-docs search_research_reports --params '{"query":"贵州茅台 2026 年增长预期与目标价","start_date":"2025-01-01","end_date":"2026-06-30","sec_ids":"600519.SH"}'

# 财报原文：优先带 financial_report_tags 投研标签（见「关键参数 Schema」），此处为无标签的基础用法
suntime-mcp-cli suntime-financial-docs search_stock_financial_reports --params '{"query":"贵州茅台 2024 年年报管理层讨论","start_time":"2025-01-01","end_time":"2025-04-30","sec_ids":"600519.SH"}'

# 财报原文 + 投研标签：战略展望与经营指引类段落
suntime-mcp-cli suntime-financial-docs search_stock_financial_reports --params '{"query":"贵州茅台 2024 年年报 公司发展战略 经营指引","financial_report_tags":"504102,504103","start_time":"2025-01-01","end_time":"2025-04-30","sec_ids":"600519.SH"}'

路径 B：先 list 后 search——指定标的中已知要看哪几篇（或要先浏览目录挑重点）时用，两步：list 拿清单和 ID → 按篇精准召回原文：

# 第一步：拉标的公告清单（ann_id 即返回的 id 字段）
suntime-mcp-cli suntime-financial-docs get_stock_announcements_list --params '{"data_scope":"4","sec_ids":"600519.SH","start_time":"2026-08-15","end_time":"2026-08-20","limit":20}'

# 第二步：选中公告后传 ann_id 召回原文（可多个）
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"贵州茅台 半年度业绩说明会 召开安排","data_scope":"4","ann_id":"10408776","sec_ids":"600519.SH"}'

# 研报同理：先列研报目录（query 必填，描述研究主题），report_id 即返回的 id 字段
suntime-mcp-cli suntime-financial-docs get_research_reports_list --params '{"query":"600519.SH 贵州茅台 盈利预测 目标价","sec_ids":"600519.SH","start_date":"2026-05-01","end_date":"2026-08-20","limit":10}'

# 再按 report_id 召回选定研报的观点段落（可多个）
suntime-mcp-cli suntime-financial-docs search_research_reports --params '{"query":"贵州茅台 2026年中报点评 提价 直销改革 盈利预测","report_id":"10462700,10448908","sec_ids":"600519.SH"}'

两条路径的选择：

A 股事件追踪（标签化）

# 高管增减持
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"贵州茅台 高管 增持 减持","start_time":"2025-01-01","end_time":"2026-06-30","data_scope":"4","tags":"405101","sec_ids":"600519.SH"}'

# 机构调研
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"宁德时代 机构调研","start_time":"2025-01-01","end_time":"2026-06-30","data_scope":"4","tags":"406101","sec_ids":"300750.SZ"}'

# 业绩说明会
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"贵州茅台 业绩说明会","start_time":"2025-01-01","end_time":"2026-06-30","data_scope":"20","sec_ids":"600519.SH"}'

港股公告

# 港股财报检索（2024 年报按报告期≠发布期换算：2025-01-01 ~ 2025-12-31）
suntime-mcp-cli suntime-financial-docs search_hkstock_announcements --params '{"query":"腾讯控股 2024 年报 业绩回顾 分红","start_time":"2025-01-01","end_time":"2025-12-31","sec_ids":"00700.HK"}'

# 港股公告列表：按 sec_ids + tags + 日期窗过滤
suntime-mcp-cli suntime-financial-docs get_hkstock_announcements_list --params '{"sec_ids":"00700.HK","tags":"402101","start_time":"2026-08-01 00:00:00","end_time":"2026-08-20 23:59:59","limit":5}'

# 港股全市场扫描（不传 sec_ids，同 A 股盘点模式；如近两周盈喜盈警）
suntime-mcp-cli suntime-financial-docs get_hkstock_announcements_list --params '{"tags":"402102","start_time":"2026-08-01 00:00:00","end_time":"2026-08-20 23:59:59","limit":200}'

ETF 公告 / 新闻舆情 / ETF 研报

低频场景命令示例外置至 references/patterns.md（ETF 公告的 list→search 双场景与选择建议、新闻舆情、ETF 研报）。核心要点：

• ETF 公告：get_etf_announcement_list（必填 sec_ids，支持 first_class/second_class 分类）拿 ann_id → search_etf_announcements 召回原文，范式与「单股检索」路径 B 相同
• 新闻舆情：search_financial_news 支持宏观主题（不传 sec_ids）与个股舆情（传 sec_ids）
• ETF 研报：search_etf_research_reports（sec_ids 必须带后缀）

开放式主题探索（无标的裸 query，全库语义检索）

典型问题："AI 对消费电子产业链的影响""存储芯片涨价利好哪些公司"——无标的、无清单要求，要的是跨标的观点聚合。

# 研报：卖方观点聚合（最常用）
suntime-mcp-cli suntime-financial-docs search_research_reports --params '{"query":"AI 大模型对消费电子产业链的影响 投资机会","start_date":"2026-01-01","end_date":"2026-08-20"}'

# 新闻：市场反应与事件解读
suntime-mcp-cli suntime-financial-docs search_financial_news --params '{"query":"存储芯片涨价 影响哪些公司","start_time":"2026-07-01","end_time":"2026-08-20"}'

# 公告原文：行业性事件的公司表态
suntime-mcp-cli suntime-financial-docs search_stock_announcements --params '{"query":"存储芯片涨价 上市公司 业绩影响","data_scope":"4","tags":"402103","start_time":"2026-07-01","end_time":"2026-08-20"}'

裸 query 的结果用于观点聚合与线索发现，召回条数不可控、不保证穷尽；发现目标标的后再切到场景 2（单股深挖）或场景 3（清单盘点）。

注意事项

1. 参数名以 tool_list schema 为准，禁止类比迁移：本 MCP 检索类工具的语义检索参数统一是 query（没有 keyword / keywords / q）。构造参数前先查 schema（见「标准调用流程」第 2 步）。
2. 日期参数分两组：资讯/A股/港股 6 工具用 start_time + end_time（yyyy-MM-dd HH:mm:ss）；研报/ETF 6 工具用 start_date + end_date（yyyy-MM-dd）。均可选，不传 = 不限时间。用户未指定时间时套用「默认时间窗口」，空结果时扩大窗口重试（详见上方参数说明）。
3. 报告期 vs 发布期：金融数据常见错误就是"用户问 2025 年报"时把日期设成 2025-01-01..2025-12-31，实际应设成 2026-01-01..2026-04-30。
4. 降级重试时 query 必须改写：不能传与上次相同的 query，否则会再次失败。
5. 列表 vs 检索：get_xxx_list 返回元数据列表（标题、日期、ID），适合浏览目录/事件清单，也是无具体标的的盘点型任务（"本周 XX 公告汇总"）的唯一正确入口——get_stock_announcements_list 不传 sec_ids 即全市场扫描（财报类事件配 tags=402101,402102）；search_xxx 返回 RAG 原文段落，适合深挖内容。盘点型任务标准链路见「全市场事件盘点」。
6. A 股公告的 data_scope 为可选：默认 "4,14,17,20"（全部数据源）；只需法定公告时单独传 "4"。
7. tags 适用范围：search_stock_announcements 的 tags 仅在 data_scope=4 时生效；search_hkstock_announcements 的 tags 直接使用，无需 data_scope。
8. 列表工具支持 limit：默认 20，最大 200。列表按发布时间降序返回，条数 = limit 时可能截断，缩小时间范围分段获取。
9. 港股代码 5 位带前导 0：00700.HK，不要写成 0700.HK 或 7700.HK。
10. RAG 检索返回原文段落：不是结构化数据。如需财务数字，配合 suntime-stock 的结构化工具使用。
11. 多代码 RAG 召回不全：search_xxx 传多个 sec_ids 时召回可能只覆盖部分标的（见 sec_ids 参数说明）——要求每家都有原文时按代码逐个单查；ann_id 批量召回不受此影响。

与结构化工具的协作

工具名、参数名、必填与可选以 tool_list 实时输出为准（缓存 1 小时，--refresh 强制刷新）：MCP 升级新增/变更参数后以清单为准，本文档速查表仅供参考。

BASH复制

suntime-mcp-cli suntime-financial-docs tool_list