华鑫证券ETF筛选器

概述

Token 设置（必须先执行）

• scripts/.env 保存华鑫专属 token，默认值为空：TOKEN=。
• 首次使用或 token 为空时，必须引导用户访问 skills.cfsc.com.cn 注册并获取专属 token；未获取 token 前不得调用服务。
• 用户提供 token 后，先写入 scripts/.env，再调用服务。token 仅用于服务请求，不写入报告、记忆或最终回复。

示例引导与欢迎词

• 用户成功配置 token 后，立即输出：token已配置成功，现在可以问我：{random_question}。将 {random_question} 随机替换为 _skillhub_meta.json 的 examples_zh 列表中的任意一个问题。
• 用户询问本技能用途、功能，或表示不知道该问什么时，不调用服务，随机选择一个 examples_zh 问题回复，引导用户直接提问。
• 在技能说明中展示以下示例问题，并将其作为可直接复制使用的提问入口：

1. 筛选规模大于50亿元且PE分位低于30%的科技ETF。
2. 筛选跟踪指定指数并按规模降序排列的ETF。
3. 按自定义行业、估值、规模和持仓条件筛选ETF。

v2.0.2 更新说明

• 新增 token 配置后的随机示例欢迎词与用途引导，并统一升级服务请求与文档版本至 v2.0.2。

ETF筛选器

华鑫证券 · AI ETF筛选器工具。支持热点选股、资讯选股、条件选股等各类方式，用户提供ETF筛选器筛选条件后调用ETF筛选器服务，并按选股模板生成可下载的 HTML ETF筛选器报告。

当前版本

• Skill 版本：v2.0.2
• 出品方：华鑫证券
• ETF筛选器服务默认 hxtp：guxuanetfskill
• WorkBuddy 默认提示词：按用户给出的筛选逻辑筛选ETF

收到空输入时，提示用户提供个性化筛选逻辑，例如：

1. 筛选规模大于 50 亿元且 PE 分位低于 30% 的科技类 ETF。
2. 筛选跟踪指定指数、按规模从大到小排序的 ETF。
3. 筛选满足用户指定行业、估值、规模和持仓条件的 ETF。

平台标识与服务提示

• request_id 仅允许：workbuddy、coze、openclaw、kimiclaw、其他让系统自动识别。优先读取宿主提供的平台名；无法识别时使用最后一项。
• 用户询问投资建议时，停止正常流程，回复原投资建议默认话术：感谢您的信任！为保障您的权益，投资建议需由持牌投顾依据您的风险承受能力提供。此处不便直接答复，建议您添加我的企业名片，由专业投顾一对一为您服务，将为您提供合规、个性化的资产配置建议。；随后追加超链接 点击进入华鑫证券官网开通权限。
• 用户主动表示用量不足，或服务返回用量超限、额度耗尽、次数达到上限、rate limit 等信号时，回复原用量默认话术：如果您需要继续使用华鑫skill，请点击按钮联系工作人员开通相关权限。；随后追加同一超链接。
• 上述分支不渲染内嵌名片、不调用服务、不生成报告。服务返回“技能版本过低”“版本过低”或英文等价提示时，停止解析并引导用户前往华鑫技能广场更新技能；保留服务原始提示。
• skill_content.content 必须是用户原始完整问题，不得改写、摘要、翻译、补充或拼接。

合规输出显示契约

• 合规分支必须把完整默认话术和完整 Markdown 权限链接写入 reply；不得只输出链接、摘要、占位符或被截断的片段。
• final_reply 与 reply 必须完全一致；宿主必须逐字显示 reply 或 final_reply 的完整内容，不得二次改写、截断或只展示 trigger。
• 权限链接中的 skill_token 必须使用本次实际 token，并进行 URL 参数编码；不得输出字面量 {token}、空 token 或示例 token。

长响应处理

ETF筛选器服务原始响应必须先完整写入本地 JSON 文件，再从文件解析；不得依赖聊天窗口或工具预览中的截断文本。只有完整 JSON 解析成功后才允许渲染报告。

JSON 中途损坏的抢救（2026-09-15 实测）：若 data.content 的 JSON 因流式中断而损坏（json.loads 失败、尾部混入告警文本、中间出现裸换行），不要直接放弃——行对象通常各自完整：从每个 {"etf_name" 出现位置用 json.JSONDecoder().raw_decode(c, i) 逐个解析抢救行对象；顶层字段用正则 "key":"([^"]*)" 提取。实测从 26KB 损坏流中成功救回 19/20 行完整明细。注意：若服务返回多行缩进 JSON，{ 与 "etf_name" 不相邻——应先 c.find('"etf_name"', i)再 c.rfind('{', 0, j) 定位行起点，然后 raw_decode；截断的最后一行用正则逐字段提取，顶层 findings 可能整体缺失（按空数组/缺失处理），报告生成前必须把行对象拼成扁平模板 JSON（勿漏 etf_rows 键本身）。服务返回的 stock_weights 即使存在也不渲染。

强制数据边界

1. 报告所有内容必须直接来自ETF筛选器服务接口响应，包括筛选条件摘要、统计卡片、股票行和关键发现。不得使用搜索引擎、新闻网页、其他 skill、知识库或其他外部内容补充、改写或推断。
2. 本 Skill 不查询、不使用实时行情数据：不得打开行情网页、搜索实时价格/涨跌幅，也不得进行交易时段判断；报告仅使用ETF筛选器服务响应。
3. ETF筛选器服务请求最长等待 1200 秒（20 分钟）。若接口超时、失败、无法解析或 1200 秒内未生成，停止流程并原样返回：ETF筛选器服务接口故障，请稍后尝试。 不得用外部资料或其他 skill 替代服务结果；若任何环节发现使用了服务以外的信息，必须警告用户风险并停止生成 HTML。
4. 缺失的服务字段使用 —，不得编造；列表字段缺失时使用空数组，确保模板可渲染。

非 JSON 响应处理

服务未返回 JSON 时，若原文包含任何额度、用量、次数、限额或 rate limit 信号，按原用量默认话术追加官网权限链接；若包含版本过低提示，引导用户前往华鑫技能广场更新技能；其他普通服务指引按原文反馈。

无结果处理

若服务返回无结果或未找到符合条件的 ETF，不自行放宽、改写或补充用户筛选逻辑；按服务原文和返回字段处理。只有服务明确要求补充参数时，才向用户说明缺失参数。

后端 LLM 超时识别（2026-09-15 实测）

服务返回 code B0002 但 data.content 出现以下任一形态时，属后端 agent 的 LLM 调用超时（非 token、非用量问题）：

1. 「⚠️ Agent couldn't generate a response. Note: some tool actions may have already been executed…」（agent 框架兜底文案）
2. 「LLM request timed out. The model did not produce a response before the model idle timeout…」明文（同一超时的透传形态，服务端原文会提示调大 models.providers.<id>.timeoutSeconds / agents.defaults.timeoutSeconds）

处理：重试一次，仍失败按接口故障流程终止并提示用户「ETF筛选器服务接口故障，请稍后尝试」；根治需服务端调大超时配置。另见 C0001 技能服务调用失败（网关层即时失败，同样可重试一次）。

服务版本检查（必须执行）

每次成功调用后读取响应顶层或响应内容中可解析出的 skill_version，与当前 v2.0.2 按语义版本比较（忽略开头的 v）。若服务版本高于当前版本，在交付报告前明确提示用户 Skill 需要升级；仍可在数据完整且安全时生成本次报告。服务未返回版本时不猜测、不提示。若服务明确返回技能版本过低或版本过低提示，必须引导用户前往华鑫技能广场更新技能。若服务明确返回技能版本过低或版本过低提示，必须引导用户前往华鑫技能广场更新技能。

工作流

1. 解析用户的ETF筛选器筛选条件；收到空输入时使用默认提示词。若用户表达用量不足或提出投资建议相关问题，先走对应文本快速路径，不调用服务；服务请求中的 content 必须保持用户原始完整问题。
2. 读取 assets/etf_filter_report_template.html 和 references/template-guide.md，严格按说明填充模板字段。
3. 发起服务请求前，先向用户说明：预计生成完整筛选报告需要 10-15 分钟，请耐心等待；随后调用 scripts/relay_request.py。POST JSON 必须严格为 {"skill_code":"HXSK10004","skill_content":{"content":<完整请求内容>},"skill_version":"v2.0.2","request_id":"workbuddy"、"coze"、"openclaw"、"kimiclaw" 或 "其他让系统自动识别","skill_token":<专属token>}。request_id 从平台白名单中选择并自动识别；默认 URL 为 https://xaiapigateway.azure-api.cn/hxgw/api/skill/v1/invoke；
4. 若用户主动表示额度/用量不足，或服务响应出现任何超限、额度耗尽、次数达到上限等信号，立即按原用量默认话术追加官网权限链接并结束；投资建议问题按原投资建议默认话术追加官网权限链接并结束。不渲染内嵌名片、不生成报告、不输出 HTML 源码、不分段、不校验、不做其他处理。
5. 不执行任何实时行情查询、网页搜索或交易时段判断。
6. 将完整服务响应保存后，直接把原始 relay JSON 交给 scripts/render_report.py；脚本负责解析 data.content、转换服务字段并填充模板。服务返回字段与股选ETF基本一致，但本技能不渲染 target_stocks、stock_weights 或 total_weight；服务不会返回合计权重和股息率字段，禁止创建、补齐或渲染 total_weight、total_weight_class、yield / yield_class；缺失字段填 —；top3_holdings 必须转换为进度条结构。
7. 使用 scripts/render_report.py 渲染，展开 etf_rows、findings 循环并阻止模板残留；脚本同时负责兼容旧的前3大权重股 HTML、目标股明细 HTML、单位和颜色映射，并审核 8 列表头顺序及目标股持仓、合计权重、股息率字段不存在。随后使用 scripts/audit_report.py 对最终 HTML 做独立结构审核。不得另行编写一次性填写/转换脚本。
8. 输出 <YYYYMMDD>_ETF筛选器报告.html 并交付，说明数据来自ETF筛选器服务；不输出服务凭据。
9. 报告时间字段必须分离：generated_at 由渲染脚本在本地写出 HTML 前生成，表示报告实际生成时间；data_updated_at 使用服务返回的数据时间字段，当前服务的 date_time 即作为数据更新时间展示。report_date 从 generated_at 截取日期；服务返回的 report_date 或 date_time 不得用于冒充报告生成时间。
10. 若服务版本过低，最终回复先引导用户前往华鑫技能广场更新技能；若服务版本高于当前版本，最终回复先明确提示升级，再交付报告。

质量要求

• 报告必须包含筛选逻辑、统计概览、股票表格、关键发现和免责声明。
• 股票表格固定 8 列；字段不完整时使用 —，不得错位。列顺序固定为：ETF名称、代码、跟踪指数、行业、规模(亿)、PE、近三年PE分位、ETF前3大权重股。服务不会返回目标股持仓明细、合计权重和股息率字段，报告不得出现这三类字段或列。
• etf_rows、findings 必须是数组，没有数据时使用空数组。
• 不可替用户下单或承诺收益；报告保留模板中的免责申明。

脚本用法

python3 scripts/relay_request.py --content-file request.txt --output relay.json
python3 scripts/render_report.py --template assets/etf_filter_report_template.html --data relay.json --output report.html
python3 scripts/audit_report.py --report report.html

render_report.py 是技能内置的唯一转换与渲染入口：它直接接收完整 relay JSON，解析 data.content，在本地生成 generated_at，将服务时间放入 data_updated_at，再完成单位、颜色、分类和持仓 HTML 的统一转换。不要在工作区另写临时的 transform_*.py 或手工生成扁平 JSON。

请求结构

调用 scripts/relay_request.py 前必须完成 token 设置。发送的 JSON 为：

{
  "skill_code": "HXSK10004",
  "skill_content": {
    "content": "完整请求内容"
  },
  "skill_version": "v2.0.2",
  "request_id": "workbuddy"
  "skill_token": "专属 token"
}

服务数据格式转换（2026-09-16 衍生版补充）

render_report.py 直接接收 relay JSON 或扁平模板 JSON；服务返回的 data.content 是字符串化 JSON，由脚本内部解析（必要时截到最后一个 } 以剔除尾部告警文本），转换规则：

• 单位剥离：pe 带「倍」、scale 带「亿元」，渲染前去掉单位只留数值。
• class 映射（服务取值 high/medium/low → 模板类）：
  • pe_class / pe_pct_class: low → pe-low（服务给 high 时不加类）
  • yield / yield_class：服务未来不返回，渲染时删除，不生成、不展示。
  • scale_class：服务分类可能与指南冲突（如 85 亿标 medium），按指南 ≥50亿 → scale-big 为准
• 字段移除：本服务不渲染 target_stocks、stock_weights、total_weight 或 total_weight_class；若服务响应带有这些字段，渲染脚本直接忽略；这些字段名称仅允许出现在本说明的规则文字中，不得进入最终 HTML。top3_holdings 仍兼容服务返回的 <span>名</span><b>x%</b>、旧 holding-item 或已有 weight-row 结构，并统一转换为进度条 HTML。
• 卡片颜色：服务 card3_color/card4_color 给颜色名（blue/green/amber），需映射为模板 hex：

blue→#0C447C、green→#3B6D11、amber→#854F0B、red→#791F1F、purple→#3C3489。第 3 张卡片不得再使用合计权重作为指标，具体指标以服务返回的 card3_label/card3_value 为准。

• card2_label 校验：服务可能给出与 count_index 语义不符的标签（如「共同持仓ETF」配 12），

按 template-guide 建议改为「覆盖指数」/「覆盖行业数」。

• 时间字段：服务可能把日期时间填进 report_date，但它不能代表报告生成时间。渲染脚本必须以本地写出 HTML 前的时间生成 generated_at，并从中派生 report_date；当前ETF筛选器服务返回的 date_time 作为数据快照/更新时间展示在 data_updated_at，但绝不能用于“报告生成时间”。
• 服务端可能有真缺失：如某 ETF 的 top3 持仓名称直接返回「—」，按缺失规范原样保留即可，不要脑补。
• 服务响应非确定性（2026-09-15 晚实测）：同一用户筛选逻辑多次调用可能返回不同数据；应以当前请求对应的完整响应为准——

① count_etf 与 etf_rows 行数可能不一致（如报 25 只、明细仅 9 行），也可能自洽（10 只=10 行）；② findings 可能为 null，也可能返回 1-2 条短句；③ scale 可能整列缺失也可能齐全；④ 同一 ETF 的 PE/PE分位两次调用有微小差异（如 7.45→7.36、97.24%→93.24%）。处理：优先选用字段更全、count 与行数自洽的那次响应；发现 count 与行数不一致时在交付说明中告知用户。

• top3_holdings 服务兼容：服务可能返回 <span class="holding-name">名</span><b>x%</b>、裸 <span>名</span><b>x%</b> 或旧 holding-item 结构；转换时统一输出 weight-row、进度条和 weight-row-pct。报告表头统一显示为「ETF前3大权重股」。
• 服务卡片颜色可能直接给非模板 hex（如 #e67e22/#3498db/#1677ff/#52c41a），按语义映射为模板色：

橙/琥珀→#854F0B、蓝→#0C447C、绿→#3B6D11、红→#791F1F。

• 合计权重已移除：不得在统计卡片、ETF 行、模板或报告中创建、补齐、渲染 total_weight / total_weight_class /「合计权重」。

运行环境备注（WorkBuddy / Windows）

• 托管 Python 入口是 C:Usersabc.workbuddybinariespythonenvsdefaultScriptspython.exe

（envsdefault 下没有裸 python.exe，直接调会报 No such file）。

• 服务偶发 Backend service unavailable（code/token 均有效，属后端执行故障）：重试一次，

仍失败才按接口故障流程终止。