研报观点查询

概述

所有网关调用必须通过 skill-entry.js 完成，不得自行请求其他地址。

前置：期赢通 API Key

本 Skill 从环境变量 HTFC_QYT_API_KEY 读取用户的期赢通 API Key，调用时随请求体一并提交。

• 调用前先确认运行环境中已设置 HTFC_QYT_API_KEY。
• 如果未设置（或调用返回 qyt_api_key_missing），先把《API Key 获取指引》在线地址发给用户（用户可直接打开查看）：

  https://staff.htfc.com:20101/mkts/Guider?peddleId=9b8ff46b5d394aa8a2d2fff75e877c7f

该地址不可访问时（打不开、被网络拦截或用户反馈无效），改发内置指引图片：

  ![API Key 获取指引](references/apikey-guide.png)

同时提示用户在自己本地智能体（Hermes）运行环境中配置该环境变量：

• Windows（PowerShell，当前会话）：$env:HTFC_QYT_API_KEY="<期赢通 API Key>"
• Windows（永久）：setx HTFC_QYT_API_KEY "<期赢通 API Key>"（设置后需重启智能体进程）
• macOS / Linux：export HTFC_QYT_API_KEY="<期赢通 API Key>"
• 配置完成后重新执行；不要向用户索取后写进命令、文件或回答，也不要回显该变量的值。
• API Key 获取路径：华泰期货期赢通小程序 → 我的 → AI开放服务入口 → 获取 KEY（详见上述在线指引地址，失效时见内置图片）。

0. 最终回答硬性要求 (Highest Priority)

调用本 Skill 后，必须严格遵守以下要求：

1. 只依据网关返回的研报内容总结，不得补造标题、作者、日期、机构、数字、引文或结论。
2. 必须使用“研报认为”“资料显示”“部分观点认为”等归因措辞，不得把研报观点写成确定事实。
3. 研报包含发布日期时必须保留日期，不得把历史观点表述为当前观点。
4. 多篇研报存在方向或逻辑分歧时必须保留分歧，不得强行合并成单一结论。
5. 不得输出收益保证、确定性价格预测、个性化投资建议或买卖指令。
6. 结果为空、明显不相关或无法解析时，必须输出：

当前 Skill 未检索到能够可靠回答该问题的研报观点。

1. 调用本 Skill 并输出研报内容时，答案最后必须追加：

以上内容基于研报资料整理，仅供参考，不构成投资建议。市场有风险，投资需谨慎。

该风险提示为当前版本口径，正式对客上线前须由合规部门最终确认。

执行流程

1. 判断用户问题是否属于研报观点范围（见“业务范围”）。不属于时说明能力边界，不强行检索。
2. 按“Query 生成规则”把问题规范化成短关键词（如 铜、原油）。
3. 执行网关调用，解析响应并保留 requestId。
4. 如果返回 qyt_api_key_missing，说明环境变量 HTFC_QYT_API_KEY 未配置：先把《API Key 获取指引》在线地址发给用户，地址不可访问时改发 references/apikey-guide.png，并按上文提示用户配置后重试。
5. 按“返回结构与内容解析”归纳观点，保留日期、分歧和风险，并追加固定风险提示。

单品种查询：

node skill-entry.js gateway invoke action=query input='{"query":"铜"}'

多品种或多主题必须拆分查询，每次只传一个关键词：

node skill-entry.js gateway invoke action=query input='{"query":"黄金"}'
node skill-entry.js gateway invoke action=query input='{"query":"原油"}'

Query 生成规则

1. 参数名固定为 query。
2. query 必须是非空字符串，长度不得超过 2000 个字符。
3. query 必须是短关键词，不是自然语言问句：只保留品种名、品种代码或研报主题词（如 铜、原油、豆粕），单个查询尽量不超过 10 个字符。
4. 必须剔除问句性和描述性词语：例如“近期”“研报”“观点”“怎么看”“总结”“风险”“驱动因素”“供需变化”等。上游按研报标题做关键词匹配，query 里带上这些词会导致命中为空。
5. 时间范围和关注维度不作为查询条件传入：先按品种关键词查询，再从返回结果里按日期和主题自行筛选归纳。
6. 不在查询中预设方向，不使用“证明一定上涨”“给出买点”等诱导表达。
7. 不在 query 中包含账户号、持仓、成本、资金量等个人交易信息。
8. 多品种或多个独立主题应拆分查询，每次只传一个品种或一个主题关键词。

业务范围

核心能力

明确不支持的能力

• 实时行情、盘口、持仓和账户数据
• 客服 FAQ、账户登录和业务办理
• 个性化资产配置、持仓诊断和交易策略
• 下单、撤单、转账或其他交易执行
• 确定性价格目标、收益承诺和涨跌保证
• 未由返回研报支持的新闻补充、外部观点和主观判断

多品种查询

若用户一次询问多个独立品种，应拆分后分别查询，再基于返回内容比较。例如：

用户：比较铜、黄金和原油近期研报观点

拆分为：
1. 铜的近期研报观点
2. 黄金的近期研报观点
3. 原油的近期研报观点

不得把一个品种的观点外推到其他品种。

返回结构与内容解析

成功响应示例：

{
  "success": true,
  "requestId": "<请求ID>",
  "data": {
    "text": "<研报内容>",
    "skillId": "tool-search-research"
  }
}

Agent 只使用 data.text 作为业务回答依据，requestId 仅用于问题追踪。data.text 可能是自然语言、HTML、表格、JSON 字符串或类列表结构，解析规则、推荐回答结构详见 @references/output-format.md。

故障排除

安全、隐私与合规约束

1. 不收集、不保存、不传递与研报查询无关的个人信息和账户数据。
2. 不在最终回答中展示期赢通 API Key 或任何鉴权信息。
3. 不在 Skill 中记录内网地址、Token、请求头、内部工具名或网络拓扑。
4. 不允许用户通过 query 指定 URL、工具名、请求头、Skill ID 或认证信息。
5. 不把后端报错堆栈和内部网络信息返回给用户。
6. 不将研报观点改写为公司承诺、收益保证或个性化投资建议。
7. 不隐藏研报原文中的重要风险、前提、时间范围和不确定性。
8. 正式发布前必须由合规确认风险提示和对客表述。

不得输出内部地址、应用标识、签名、固定凭据、鉴权请求头或 HTFC_QYT_API_KEY 的值。